PATCH/v1/cards/{card_id}

Actualizar una tarjeta

update_card

Autenticación

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

Parámetros de ruta

card_idstringobligatorio

Parámetros de encabezado

Idempotency-Keystring
Clave para reintentar de forma segura una escritura: de 1 a 255 caracteres ASCII imprimibles; se recomienda un UUID v4 por operación lógica. Un reintento con la misma clave en un plazo de 24 horas no vuelve a ejecutar la operación: devuelve la respuesta guardada (estado, encabezados y cuerpo) con el encabezado Idempotency-Replayed: true. La misma clave con otro método, otra ruta, otro Content-Type u otro cuerpo devuelve 409 api.idempotency_mismatch; mientras la primera solicitud sigue en curso, 409 api.idempotency_in_progress con Retry-After: 1. Tras una respuesta 5xx o 429, la clave se libera y un reintento vuelve a ejecutar la operación. La clave se aplica a la organización y a quien llama a la API (clave de API, usuario o clave de fuente personalizada).
length ≥ 1, length ≤ 255
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: CardUpdate

external_idstring | null
Establece o cambia el external_id de la tarjeta; "" o null lo elimina. Si otra tarjeta de la organización lo usa, la solicitud devuelve 409 cards.external_id_taken. El external_id de una tarjeta de una fuente no cambia (409 cards.managed_by_source).
length ≤ 512
metadataMetadataPatch
titlestring | null
owner_idinteger | null
verifier_idsarray of integer | null
verify_interval_daysinteger | null
≥ 1, ≤ 3650
tagsarray of string | null
statusstring | null
source_urlstring | null
categorystring | null
sensitiveboolean | null
table_categoriesmap of object | null

Respuestas

200Respuesta correcta

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.
Idempotency-Replayed
true significa que la respuesta se reprodujo a partir de la guardada para esta Idempotency-Key: la operación no se volvió a ejecutar.

application/json

Objeto: Card

expandedCardExpanded
permissionsObjectPermissionList
accessstring
Valores permitidos: wholepartial
access_contactstring
A quién dirigirse para obtener acceso (solo cuando access=partial).
aclobject
Campos
- verifybooleanobligatorio
- writebooleanobligatorio
categorystringobligatorio
category_confidencenumber | nullobligatorio
category_lockedbooleanobligatorio
category_reviewbooleanobligatorio
category_sourceCategorySource | nullobligatorio
collectionstringobligatorio
collection_idintegerobligatorio
collection_titlestring
commentsarray of CardComment
content_jsonContentJSON | null
Contenido del editor de la última versión publicada. El campo puede no aparecer; en ese caso, obtenga el contenido del editor a partir de un borrador (POST /v1/drafts con card_id).
editing_lockEditingLock | null
Bloqueo de edición activo. El campo puede no aparecer; en ese caso, el editor sabe quién tiene el bloqueo por la respuesta 409 cards.locked de POST /v1/cards/{card_id}/lock.
created_atstring (date-time)obligatorio
days_since_verifiedintegerobligatorio
errorstring | nullobligatorio
eventsarray of CardEvent
feedback_negintegerobligatorio
feedback_posintegerobligatorio
foldersarray of CardFolderRef
Solo en la lista de tarjetas: las carpetas que contienen la tarjeta (las que el usuario puede ver), con sus rutas desde la raíz de la colección. Una lista vacía significa que la tarjeta no está en ninguna carpeta.
has_tablesboolean
Solo en la lista de tarjetas.
hidden_partsboolean
idstringobligatorio
jobJob | null
kindCardKindobligatorio
org_idintegerobligatorio
owner_activeboolean | null
owner_idinteger | nullobligatorio
owner_namestring | nullobligatorio
pagesinteger | nullobligatorio
parserstring | nullobligatorio
Analizador del documento como código neutro: document (estructura completa: páginas, títulos, tablas, páginas escaneadas), pdf (la capa de texto del PDF), docx, xlsx, csv, markdown, html, text. La lista puede ampliarse.
partsarray of CardPartobligatorio
sensitivebooleanobligatorio
sha256string | nullobligatorio
sizeintegerobligatorio
snoozed_atstring (date-time) | null
snoozed_byinteger | null
snoozed_untilstring | null
source_changedbooleanobligatorio
source_pathstring | nullobligatorio
source_urlstring | nullobligatorio
statusstringobligatorio
Valores permitidos: processingreadyerrorarchived
tablesarray of CardTable
tagsarray of stringobligatorio
titlestringobligatorio
trustnumberobligatorio
trust_if_verifiednumber
trust_partsTrustPartsobligatorio
updated_atstring (date-time)obligatorio
verificationVerificationobligatorio
verified_atstring (date-time) | nullobligatorio
verified_byinteger | nullobligatorio
verified_by_namestring | null
verifier_idsarray of integerobligatorio
verifiersarray of object
Campos
- activebooleanobligatorio
- idintegerobligatorio
- namestringobligatorio
verify_interval_daysintegerobligatorio
versionintegerobligatorio
versionsarray of CardVersion
source_archiveArchiveSource
created_byinteger | null
manual_optionsobject
Configuración manual del análisis (vista previa).
doc_kindDocKind | null
Tipo de documento. null si el tipo no está determinado (por ejemplo, en las tarjetas indexadas antes de que existieran los tipos de documento).
doc_kind_confidencenumber | null
Grado de certeza del tipo de documento, de 0 a 1.
doc_kind_sourcestring | null
Qué determinó el tipo: reglas (rules), un usuario (manual) o la clasificación automática. La lista puede ampliarse: trate un valor desconocido como clasificación automática.
Valores permitidos: rulesmanualnull
invoiceDocInvoiceExtraction | null
Campos de una factura, una nota de crédito o un recibo (solo para estos tipos, y solo en la tarjeta, no en la lista). null si no tiene acceso a todo el documento, porque los campos se extraen del documento completo.
warningsarray of ReviewWarning
Advertencias del análisis del documento (ReviewWarning; solo en la tarjeta, no en la lista).
enrichmentCardEnrichmentStatus | null
Estado del enriquecimiento (solo en la tarjeta, no en la lista). El tipo de documento, los campos de la factura y los registros financieros se añaden en segundo plano después de la indexación y pueden recalcularse más tarde; aparecen en la tarjeta cuando están listos. null significa que no hay estado disponible (la tarjeta se indexó sin enriquecimiento en segundo plano).
external_idstring | null
ID de la tarjeta en el sistema del integrador. Es único en la organización entre las tarjetas que no proceden de fuentes; null significa que no está definido. /v1/cards-by-external-id/{external_id} lee y sustituye la tarjeta a partir de él.
length ≤ 512
metadataMetadata

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

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

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

Códigos de error

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

Reintentos seguros

Envíe un encabezado Idempotency-Key (por ejemplo, un UUID) con cada POST y PATCH. Un reintento con la misma clave en un plazo de 24 horas devuelve la respuesta guardada en lugar de volver a ejecutar la 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 PATCH 'https://api.sursa.com/v1/cards/CARD_ID' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"crm-1042","metadata":{"key":"string"},"title":"Refund policy"}' \
  -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.

Idempotency-Key header

X-View-As header

card_id path *

Idempotency-Key

Si este campo está vacío, se genera una clave nueva para cada solicitud.

Cuerpo de la solicitud (JSON)