PUT/v1/cards-by-external-id/{external_id}

Crear o reemplazar una tarjeta por su ID externo

upsert_card_by_external_id

Crea o reemplaza una tarjeta por el external_id del integrador. Envíe texto como application/json (CardTextUpsert) o un archivo como multipart/form-data (CardFileUpsertForm, con las mismas comprobaciones del archivo que POST /v1/cards). Si la organización no tiene ninguna tarjeta con este external_id, la tarjeta se crea en la colección y la carpeta indicadas en el cuerpo (201). En otro caso, el contenido se reemplaza por una versión nueva y se vuelve a indexar igual que una versión nueva de un archivo, y los datos de la tarjeta (título, etiquetas, responsable, categoría, metadata) toman los valores pasados (200). Un contenido sin cambios no crea una versión nueva (status: skipped, reason: unchanged), por lo que repetir la solicitud es seguro incluso sin Idempotency-Key. Cuando se pasa metadata, reemplaza el objeto completo. El acceso se comprueba como para una subida cuando la tarjeta se crea y como para una actualización de la tarjeta cuando se reemplaza. El contenido de una tarjeta que quien llama a la API solo ve en parte no se reemplaza (403 cards.content_whole_access). Las tarjetas de fuentes no se sobrescriben de esta forma: si el external_id pertenece a un documento de una fuente personalizada, o la tarjeta encontrada la mantiene una fuente, la solicitud devuelve 409 cards.managed_by_source. Cambiar el contenido retira la verificación de la tarjeta, como cualquier versión nueva (motivo update).

Autenticación

Envíe una clave de API en el encabezado Authorization: Authorization: Bearer <clave>.

Parámetros de ruta

external_idstringobligatorio
external_id de la tarjeta: una cadena de 1 a 512 caracteres, única en la organización.
length ≥ 1, length ≤ 512

Parámetros de encabezado

X-View-Asstring
Solo para claves de API con el rol admin. Ejecuta la solicitud como el perfil de datos <profile>[:viewer|verifier|editor], por ejemplo employee:viewer. La clave de instalación no puede usar este encabezado (403).

Parámetros de cookie

kb_view_asstring
Cookie del modo «View as» para una sesión. POST /auth/view-as la establece y DELETE /auth/view-as la elimina.

Cuerpo de la solicitud

application/json

Objeto: CardTextUpsert

titlestring
length ≥ 1, length ≤ 200
bodystringobligatorio
Texto de la tarjeta en el formato content_type.
length ≥ 1, length ≤ 500000
content_typeCardTextContentType
collectionstring
Colección por nombre, al crear la tarjeta. De forma predeterminada, la colección predeterminada de la instalación.
collection_idinteger | null
Colección por ID, al crear la tarjeta. Cuando también se envía collection, prevalece collection_id.
folder_idstring | null
Carpeta de la colección para la tarjeta nueva, con las mismas comprobaciones que folder_id de una subida de archivo.
length ≤ 64
tagsarray of string | null
items ≤ 30
categorystring | null
length ≤ 60
sensitiveboolean | null
owner_idinteger | null
verify_interval_daysinteger | null
≥ 1, ≤ 3650
metadataMetadataPatch
asyncboolean
true responde de inmediato e indexa la tarjeta en la cola; false responde después de la indexación.
Predeterminado: false

multipart/form-data

Objeto: CardFileUpsertForm

filestring (application/octet-stream)obligatorio
titlestring | null
Título de la tarjeta. Si no se envía, una tarjeta nueva recibe el nombre del archivo y una tarjeta existente conserva su título.
length ≤ 200
collectionstring
collection_idinteger | null
folder_idstring | null
length ≤ 64
tagsstring
Etiquetas separadas por comas.
owner_idinteger | null
verify_interval_daysinteger | null
categorystring | null
sensitiveboolean | null
metadatastring | null
metadata: un objeto JSON como valor del campo del formulario. Las reglas son las de MetadataPatch.
asyncboolean
Predeterminado: false

Respuestas

200La tarjeta ya existía. Su contenido se reemplazó (`queued`, `ready`, `error`) o no cambió (`skipped`).

Encabezados de la respuesta

RateLimit-Policy
Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.
RateLimit
Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).
X-RateLimit-Remaining
Solicitudes restantes del límite más estricto.
X-RateLimit-Reset
Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: UploadResult

statusstringobligatorio
Valores permitidos: queuedskippedreadyerror
job_idinteger
jobJob
cardCard | null
duplicatetrue
card_idstring | null
reasonstring
unchanged o an identical file is already indexed.
tablesinteger
timingsobject
Campos
- total_snumber
errorstring

201La tarjeta se creó (`queued` para una solicitud asíncrona; `ready` o `error` para una síncrona).

Encabezados de la respuesta

RateLimit-Policy
Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.
RateLimit
Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).
X-RateLimit-Remaining
Solicitudes restantes del límite más estricto.
X-RateLimit-Reset
Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: UploadResult

statusstringobligatorio
Valores permitidos: queuedskippedreadyerror
job_idinteger
jobJob
cardCard | null
duplicatetrue
card_idstring | null
reasonstring
unchanged o an identical file is already indexed.
tablesinteger
timingsobject
Campos
- total_snumber
errorstring

400La solicitud no es válida: el valor de un parámetro o el estado del objeto no permiten la acción (`detail` es un mensaje).

Encabezados de la respuesta

RateLimit-Policy
Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.
RateLimit
Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).
X-RateLimit-Remaining
Solicitudes restantes del límite más estricto.
X-RateLimit-Reset
Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

401No se enviaron credenciales (ni una cookie de sesión ni una clave de API) o no se encontró la clave.

Encabezados de la respuesta

RateLimit-Policy
Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.
RateLimit
Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).
X-RateLimit-Remaining
Solicitudes restantes del límite más estricto.
X-RateLimit-Reset
Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

402La organización ha alcanzado un límite del plan (tarjetas, almacenamiento o usuarios). `error.details` contiene `kind`, `limit` y `used`.

Encabezados de la respuesta

RateLimit-Policy
Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.
RateLimit
Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).
X-RateLimit-Remaining
Solicitudes restantes del límite más estricto.
X-RateLimit-Reset
Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

403La acción no está permitida: el rol no es suficiente, no hay acceso a la colección o a la tarjeta, la solicitud se ejecuta en modo «View as», o la organización está suspendida o eliminada (`detail` es un objeto con `code: org_suspended | org_deleted`).

Encabezados de la respuesta

RateLimit-Policy
Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.
RateLimit
Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).
X-RateLimit-Remaining
Solicitudes restantes del límite más estricto.
X-RateLimit-Reset
Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

404El objeto no existe o no está disponible para usted. La API no confirma la existencia de un objeto restringido.

Encabezados de la respuesta

RateLimit-Policy
Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.
RateLimit
Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).
X-RateLimit-Remaining
Solicitudes restantes del límite más estricto.
X-RateLimit-Reset
Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

409El estado del objeto no permite la acción, por ejemplo, un duplicado, una indexación en curso o un trabajo ya procesado.

Encabezados de la respuesta

RateLimit-Policy
Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.
RateLimit
Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).
X-RateLimit-Remaining
Solicitudes restantes del límite más estricto.
X-RateLimit-Reset
Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

413El cuerpo de la solicitud supera el tamaño permitido.

Encabezados de la respuesta

RateLimit-Policy
Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.
RateLimit
Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).
X-RateLimit-Remaining
Solicitudes restantes del límite más estricto.
X-RateLimit-Reset
Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

415El formato del archivo no es compatible.

Encabezados de la respuesta

RateLimit-Policy
Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.
RateLimit
Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).
X-RateLimit-Remaining
Solicitudes restantes del límite más estricto.
X-RateLimit-Reset
Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

422Error de validación: el cuerpo o los parámetros no coinciden con el esquema (`detail` es una lista de errores de validación), o el valor de un parámetro está fuera del rango permitido (`detail` es un mensaje).

Encabezados de la respuesta

RateLimit-Policy
Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.
RateLimit
Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).
X-RateLimit-Remaining
Solicitudes restantes del límite más estricto.
X-RateLimit-Reset
Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

429Demasiadas solicitudes (`api.rate_limited`), se agotó la cuota de la organización para el minuto, el día o el mes (`api.quota_exceeded`; `error.details` contiene `quota`, `limit` y `reset_at`), se alcanzó el límite de la organización o el servicio de respuestas está ocupado (`answers.engine_busy`). Espere el tiempo indicado en el encabezado `Retry-After`.

Encabezados de la respuesta

Retry-After
Número de segundos que hay que esperar antes de reintentar la solicitud.
RateLimit-Policy
Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.
RateLimit
Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).
X-RateLimit-Remaining
Solicitudes restantes del límite más estricto.
X-RateLimit-Reset
Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

503Un servicio del que depende esta solicitud no está disponible temporalmente. Vuelva a intentarlo más tarde.

Encabezados de la respuesta

RateLimit-Policy
Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.
RateLimit
Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).
X-RateLimit-Remaining
Solicitudes restantes del límite más estricto.
X-RateLimit-Reset
Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

Códigos de error

Códigos que este endpoint puede devolver en error.code, además de los códigos generales de cualquier solicitud.

Límites de frecuencia

Las respuestas incluyen los encabezados RateLimit y RateLimit-Policy y los anteriores X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. Una respuesta 429 lleva Retry-After en segundos: espere y vuelva a intentarlo.

← cards · Referencia de la API

curl -X PUT 'https://api.sursa.com/v1/cards-by-external-id/EXTERNAL_ID' \
  -H "Content-Type: application/json" \
  -d '{"title":"Refund policy","body":"# Refund policy\n\nRefunds are processed within 14 days.","collection":"support"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Probar

Clave de API

La clave se queda en la memoria de esta pestaña y solo se envía a https://api.sursa.com.

Las solicitudes actúan sobre los datos reales de su organización.

X-View-As header

external_id path *

Cuerpo de la solicitud (JSON)