Endpoints de negocio

Catálogo común de endpoints compartidos por PagaFactu y ZertiPay para gestionar flujos, operaciones, pagos PSD2, cuentas beneficiarias y configuraciones.

Esta página agrupa los 18 endpoints comunes que usan tanto PagaFactu como ZertiPay. El único endpoint específico de producto es la creación de un flujo PagaFactu (POST/pagafactu/v1/flows/pagafactu), que se documenta en la página de implementación de PagaFactu.

Convenciones comunes

Base URL Sandbox: https://nc-api-sandbox.zertiban.com
Headers requeridos en todas las llamadas:
- Authorization: Bearer {access_token}
- x-tenant-id: {businessUuid}

Flujos

1. Crear flujo

POST/flow/v1/flows

Content-Type: multipart/form-data. El part payload debe llevar Content-Type: application/json; si no, el servidor responde 400. Para crear cobros PagaFactu existe el endpoint específico POST/pagafactu/v1/flows/pagafactu, documentado en su página de implementación.

shell

curl -X POST https://nc-api-sandbox.zertiban.com/flow/v1/flows \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}" \
  -F 'payload={ "externalId": "...", "countryCode": "ES", "operations": [...] };type=application/json'

Raíz del payload:

Campo	Tipo	Oblig.	Descripción
`externalId`	String	No	Tu ID del flujo
`countryCode`	String	Sí	ISO 3166 (ej. `"ES"`)
`additionalLanguage`	String	No	ISO 639-1
`operations`	Array	Sí	1 operación
`documents`	Array	No	PDFs adjuntos (hasta 10)
`labels`	Array	No	Etiquetas clave-valor

Respuesta (201):

Campo	Descripción
`uuid`	UUID del flujo
`externalId`	Tu externalId
`operations[i].uuid`	UUID de la operación
`operations[i].externalId`	Tu externalId de la operación
`operations[i].id`	El `id` local que enviaste
`operations[i].url`	Enlace de pago para el pagador

2. Listar flujos

GET/flow/v1/flows

shell

# Flujos completados en los últimos 7 días
curl "https://nc-api-sandbox.zertiban.com/flow/v1/flows?q_status=COMPLETED&q_fromCreatedAt=2026-04-15T00:00:00Z&sort_by=STATUS_UPDATED_AT&sort_dir=DESC" \
  -H "Authorization: Bearer {access_token}" -H "x-tenant-id: {businessUuid}"

Query parameters:

Parámetro	Tipo	Default	Descripción
`q_uuid`	UUID	—	Filtrar por UUID de flujo
`q_externalId`	String	—	Filtrar por externalId
`q_status`	CSV	—	Estados del flujo
`q_productLabelValue`	CSV	—	Filtrar por valor de etiqueta de producto
`q_fromCreatedAt` / `q_toCreatedAt`	ISO-8601 Instant	—	Rango de creación
`q_fromStatusUpdatedAt` / `q_toStatusUpdatedAt`	ISO-8601 Instant	—	Rango de cambio de estado
`offset`	int	`0`	Posición inicial
`limit`	int	`10`	Resultados por página (max 100)
`sort_by`	String	`CREATED_AT`	`EXTERNAL_ID`, `STATUS`, `CREATED_AT`, `STATUS_UPDATED_AT`
`sort_dir`	String	`DESC`	`ASC` o `DESC`

Respuesta (200):

json

{
  "total": 150,
  "results": [
    {
      "uuid": "28ffd216-...",
      "externalId": "COBRO-2026-001",
      "status": "COMPLETED",
      "createdAt": "2026-04-22T09:00:00Z",
      "statusUpdatedAt": "2026-04-22T09:15:00Z",
      "operationsCount": 1,
      "labels": [{ "name": "pedido", "value": "12345" }]
    }
  ]
}

3. Detalle de flujo

GET/flow/v1/flows/{flowUuid}

Devuelve el flujo con el resumen de sus operaciones de pago.

shell

curl https://nc-api-sandbox.zertiban.com/flow/v1/flows/{flowUuid} \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"

Respuesta (200):

json

{
  "uuid": "28ffd216-5ee8-4e99-b1a9-511961e9c655",
  "externalId": "COBRO-2026-001",
  "status": "COMPLETED",
  "countryCode": "ES",
  "languageCode": "ES",
  "createdAt": "2026-04-22T09:00:00Z",
  "labels": [{ "name": "pedido", "value": "12345" }],
  "paymentOperations": [
    {
      "uuid": "d1faff9e-...",
      "externalId": "OP-2026-001",
      "status": "COMPLETED",
      "statusUpdatedAt": "2026-04-22T09:15:00Z",
      "expiresAt": "2026-05-22T09:00:00Z",
      "amount": 15075,
      "currency": "EUR"
    }
  ]
}

Campo	Descripción
`status`	Estado del flujo (CREATED, IN_PROGRESS, COMPLETED, REJECTED, EXPIRED, CANCELLED)
`paymentOperations[i].amount`	Importe en céntimos
`labels`	Etiquetas clave-valor enviadas al crear el flujo

4. Historial de estados de flujo

GET/flow/v1/flows/{flowUuid}/status-histories

shell

curl https://nc-api-sandbox.zertiban.com/flow/v1/flows/{flowUuid}/status-histories \
  -H "Authorization: Bearer {access_token}" -H "x-tenant-id: {businessUuid}"

Respuesta (200): Array ordenado cronológicamente.

json

[
  { "previousStatus": null, "newStatus": "IN_PROGRESS", "changedAt": "2026-04-22T09:10:00Z" },
  { "previousStatus": "IN_PROGRESS", "newStatus": "COMPLETED", "changedAt": "2026-04-22T09:15:00Z" }
]

5. Estadísticas de flujos

GET/flow/v1/flows/statistics

shell

curl "https://nc-api-sandbox.zertiban.com/flow/v1/flows/statistics?q_fromCreatedAt=2026-04-01T00:00:00Z" \
  -H "Authorization: Bearer {access_token}" -H "x-tenant-id: {businessUuid}"

Acepta los mismos filtros que GET/flow/v1/flows (sin paginación).

Respuesta (200):

json

{
  "summary": { "totalFlows": 42 },
  "groups": [
    { "key": "COMPLETED", "metrics": { "count": 38 } },
    { "key": "EXPIRED", "metrics": { "count": 3 } },
    { "key": "CANCELLED", "metrics": { "count": 1 } }
  ]
}

Operaciones

6. Listar operaciones

GET/flow/v1/operations

shell

# Operaciones completadas de un flujo concreto
curl "https://nc-api-sandbox.zertiban.com/flow/v1/operations?q_flowUuid={flowUuid}&q_status=COMPLETED" \
  -H "Authorization: Bearer {access_token}" -H "x-tenant-id: {businessUuid}"

Query parameters:

Parámetro	Tipo	Default	Descripción
`q_operationUuid`	UUID	—	Filtrar por UUID de operación
`q_flowUuid`	UUID	—	Filtrar por UUID del flujo padre
`q_externalId`	String	—	Filtrar por externalId de la operación
`q_status`	CSV	—	Estados: CREATED, OPENED, COMPLETED, REJECTED, EXPIRED, CANCELLED
`q_type`	CSV	—	Tipo de operación (`PAYMENT`, `SIGNATURE`)
`q_invoiceExternalId`	String	—	Filtrar por externalId de la factura
`q_fromCreatedAt`	ISO-8601 Instant	—	Creada desde
`q_toCreatedAt`	ISO-8601 Instant	—	Creada hasta
`q_fromStatusUpdatedAt`	ISO-8601 Instant	—	Último cambio de estado desde
`q_toStatusUpdatedAt`	ISO-8601 Instant	—	Último cambio de estado hasta
`q_amountFrom`	Long	—	Importe mínimo (céntimos)
`q_amountTo`	Long	—	Importe máximo (céntimos)
`offset`	int	`0`	Posición inicial
`limit`	int	`10`	Resultados por página (max 100)
`sort_by`	String	`CREATED_AT`	`EXTERNAL_ID`, `STATUS`, `CREATED_AT`, `STATUS_UPDATED_AT`
`sort_dir`	String	`DESC`	`ASC` o `DESC`

Respuesta (200):

json

{
  "total": 42,
  "results": [
    {
      "uuid": "d1faff9e-...",
      "externalId": "OP-2026-001",
      "status": "COMPLETED",
      "type": "PAYMENT",
      "createdAt": "2026-04-22T09:00:00Z",
      "statusUpdatedAt": "2026-04-22T09:15:00Z"
    }
  ]
}

7. Detalle de operación

GET/flow/v1/operations/{uuid}

Devuelve todos los datos de la operación, incluyendo los detalles del pago PSD2 y el paymentUuid necesario para consultar el detalle del pago una vez completado.

shell

curl https://nc-api-sandbox.zertiban.com/flow/v1/operations/{operationUuid} \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"

Respuesta (200):

json

{
  "uuid": "d1faff9e-bb8b-47bd-8b47-4f20f1a7912b",
  "externalId": "OP-2026-001",
  "flowUuid": "28ffd216-5ee8-4e99-b1a9-511961e9c655",
  "configurationUuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "type": "PAYMENT",
  "expirationOffset": "P30D",
  "expiresAt": "2026-05-22T09:00:00Z",
  "createdAt": "2026-04-22T09:00:00Z",
  "payment": {
    "paymentUuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "amount": 15075,
    "currency": "EUR",
    "concept": "Cobro 2026-001",
    "types": ["PSD2_PAYMENT"],
    "psd2Payment": {
      "type": "SINGLE_PAYMENT",
      "product": "SEPA_CREDIT_TRANSFER",
      "creditorAccount": { "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }
    },
    "subject": { "name": "Ana", "lastName": "Martinez", "email": "[email protected]" }
  }
}

Campo	Descripción
`payment.paymentUuid`	UUID del pago PSD2. Disponible una vez el estado es COMPLETED. Úsalo para llamar a `GET/payment/v1/payments/{uuid}`
`payment.amount`	Importe en céntimos
`payment.subject`	Datos del deudor tal como se enviaron al crear el flujo
`expiresAt`	Fecha de caducidad de la operación

8. Estado rápido de operación

GET /flow/v1/operations/{operationUuid}/status

Devuelve el estado actual de la operación con un payload mínimo. Ideal para polling frecuente cuando no necesitas el objeto completo.

shell

curl https://nc-api-sandbox.zertiban.com/flow/v1/operations/{operationUuid}/status \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"

Respuesta (200):

json

{
  "status": "COMPLETED",
  "actionCode": "INITIATED",
  "final": true
}

Campo	Tipo	Descripción
`status`	String	Estado actual: CREATED, OPENED, COMPLETED, REJECTED, EXPIRED, CANCELLED
`actionCode`	String	Código de acción interno de la plataforma
`final`	boolean	`true` cuando el estado es terminal (no hay más transiciones posibles)

9. Historial de estados de operación

GET/flow/v1/operations/{uuid}/status-histories

Devuelve la secuencia completa de transiciones de estado, útil para auditar el ciclo de vida de un cobro.

shell

curl https://nc-api-sandbox.zertiban.com/flow/v1/operations/{operationUuid}/status-histories \
  -H "Authorization: Bearer {access_token}" -H "x-tenant-id: {businessUuid}"

Respuesta (200): Array ordenado cronológicamente.

json

[
  { "previousStatus": null, "newStatus": "CREATED", "changedAt": "2026-04-22T09:00:00Z" },
  { "previousStatus": "CREATED", "newStatus": "OPENED", "changedAt": "2026-04-22T09:10:00Z" },
  { "previousStatus": "OPENED", "newStatus": "COMPLETED", "changedAt": "2026-04-22T09:15:00Z" }
]

Campo	Tipo	Descripción
`previousStatus`	String	Estado anterior (`null` para el estado inicial)
`newStatus`	String	Nuevo estado
`changedAt`	Instant	Momento de la transición

10. Estadísticas de operaciones

GET/flow/v1/operations/statistics

Permite obtener métricas agregadas: número total de operaciones y suma de importes, con los mismos filtros que el listado.

shell

# Total cobrado y desglose por estado del último mes
curl "https://nc-api-sandbox.zertiban.com/flow/v1/operations/statistics?q_fromCreatedAt=2026-03-22T00:00:00Z" \
  -H "Authorization: Bearer {access_token}" -H "x-tenant-id: {businessUuid}"

Acepta los mismos query parameters de filtrado que GET/flow/v1/operations (sin offset, limit, sort_by, sort_dir).

Respuesta (200):

json

{
  "summary": { "total": 42 },
  "groups": [
    { "key": "COMPLETED", "metrics": { "count": 38, "amount": 578450 } },
    { "key": "EXPIRED", "metrics": { "count": 3, "amount": 45000 } },
    { "key": "CANCELLED", "metrics": { "count": 1, "amount": 15075 } }
  ]
}

Campo	Descripción
`summary.total`	Total de operaciones que cumplen los filtros
`groups[i].key`	Valor del agrupador (estado de la operación)
`groups[i].metrics.count`	Número de operaciones en este grupo
`groups[i].metrics.amount`	Suma de importes en céntimos en este grupo

11. Cancelar operación

PUT/flow/v1/operations/{operationUuid}/cancel

Cancela una operación que todavía no ha alcanzado un estado final.

shell

curl -X PUT https://nc-api-sandbox.zertiban.com/flow/v1/operations/{operationUuid}/cancel \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"

No hay body en la petición.

Respuesta exitosa: 204 No Content

Código	Causa
`409`	La operación ya está en un estado final (COMPLETED, REJECTED, EXPIRED, CANCELLED)
`409`	La operación está en estado OPENED y el pagador tiene un pago en curso (transacción pendiente)

Si el flujo tenía esta operación como la única activa, el flujo pasará también a CANCELLED.

12. Ampliar caducidad de operación

PATCH /flow/v1/operations/{operationUuid}/expiration

Recalcula la fecha de caducidad de la operación sumando la duración indicada al momento de la llamada (expiresAt = now + duration).

shell

curl -X PATCH https://nc-api-sandbox.zertiban.com/flow/v1/operations/{operationUuid}/expiration \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}" \
  -H "Content-Type: application/json" \
  -d '{ "duration": "P7D" }'

Request body:

Campo	Tipo	Descripción
`duration`	String	Duración ISO 8601 en días únicamente (ej. `"P7D"` = 7 días, `"P30D"` = 30 días). Solo se admite el designador `D`.

Respuesta exitosa: 204 No Content

Restricciones:

La operación debe estar en un estado no final (CREATED u OPENED).
La duración mínima es 1 día (P1D).
El campo duration solo admite el designador de días (D). No se admiten horas (H) ni minutos.

13. Descargar documento de pago adjunto

GET/flow/v1/operations/{operationUuid}/payment-documents/{paymentDocumentUuid}/content

Descarga el contenido binario de un documento PDF que fue adjuntado al crear el flujo. El documentUuid se obtiene del array payment.documents en el detalle de la operación.

shell

curl https://nc-api-sandbox.zertiban.com/flow/v1/operations/{operationUuid}/payment-documents/{documentUuid}/content \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}" \
  -o documento.pdf

Respuesta: binario application/pdf con header Content-Disposition: attachment; filename="<nombre-del-fichero>". Si no hay nombre disponible, el servidor usa payment-document.pdf.

Pago PSD2

14. Detalle del pago PSD2

GET/payment/v1/payments/{uuid}

El paymentUuid está disponible en GET/flow/v1/operations/{uuid} → campo payment.paymentUuid, una vez la operación alcanza el estado COMPLETED.

shell

curl https://nc-api-sandbox.zertiban.com/payment/v1/payments/{paymentUuid} \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"

Respuesta (200):

json

{
  "psd2Payment": {
    "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "status": { "code": "ACSC", "status": "AcceptedSettlementCompleted" },
    "instructedAmount": { "amount": 15075, "currency": "EUR" },
    "remittanceInformationUnstructured": "Cobro 2026-001",
    "executionDate": "2026-04-22T09:14:00Z",
    "requestedExecutionDate": null,
    "bankPaymentId": "BANKA12345678",
    "creditorAccount": {
      "ownerName": "Mi Empresa S.L.",
      "accountNumber": "ES91210004183401234567",
      "bic": "CAIXESBBXXX",
      "country": "ES",
      "type": "IBAN"
    },
    "debtorAccount": {
      "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "accountNumber": "ES8020484097908424975543",
      "type": "IBAN",
      "currency": "EUR",
      "psuName": "Ana Martinez",
      "ownerName": "Ana Martinez",
      "bic": "BBVAESMMXXX"
    }
  }
}

Campo	Descripción
`psd2Payment.status.code`	Código ISO 20022 del estado del pago (ej. `ACSC` = liquidado)
`psd2Payment.instructedAmount`	Importe exacto que se movió
`psd2Payment.remittanceInformationUnstructured`	Concepto / referencia del pago
`psd2Payment.executionDate`	Momento en que el banco procesó el pago
`psd2Payment.requestedExecutionDate`	Solo presente en pagos programados (`FUTURE_PAYMENT`)
`psd2Payment.bankPaymentId`	Identificador del pago asignado por el banco
`psd2Payment.creditorAccount`	Cuenta beneficiaria donde se recibió el dinero
`psd2Payment.debtorAccount`	Cuenta del pagador que realizó la transferencia

Cuentas beneficiarias

Documentación detallada de campos y filtros en Cuentas beneficiarias.

15. Listar cuentas beneficiarias

GET/business-creditor-account/v1/business-creditor-accounts

shell

curl "https://nc-api-sandbox.zertiban.com/business-creditor-account/v1/business-creditor-accounts?offset=0&limit=10" \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"

Parámetro	Tipo	Default	Descripción
`offset`	int	`0`	Posición inicial
`limit`	int	—	Resultados por página
`q_status`	enum (ACTIVE / DISABLED)	—	Filtra por estado. Sin valor devuelve todas.
`q_isDefault`	boolean	—	Filtra por si es la cuenta por defecto.

16. Detalle de cuenta beneficiaria

GET/business-creditor-account/v1/business-creditor-accounts/{uuid}

shell

curl "https://nc-api-sandbox.zertiban.com/business-creditor-account/v1/business-creditor-accounts/{uuid}" \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"

Campo	Tipo	Descripción
`uuid`	UUID	`creditorAccountUuid` a usar al crear flujos
`accountNumber`	String	Número de cuenta (enmascarado)
`type`	String	Tipo de cuenta. Valor posible: `IBAN`
`alias`	String	Nombre identificativo
`status`	String	ACTIVE o DISABLED. Solo las ACTIVE aceptan pagos
`isDefault`	Boolean	Si es la cuenta beneficiaria por defecto del negocio
`aspsp.commercialName`	String	Nombre comercial del banco

Configuraciones de flujo

Documentación detallada de campos y filtros en Configuración de flujo.

17. Listar configuraciones

GET/flow-customization/v1/configurations

shell

curl "https://nc-api-sandbox.zertiban.com/flow-customization/v1/configurations?offset=0&limit=10" \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"

18. Detalle de configuración

GET/flow-customization/v1/configurations/{configurationUuid}

shell

curl https://nc-api-sandbox.zertiban.com/flow-customization/v1/configurations/{configurationUuid} \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"

Tabla resumen

Base URL Sandbox: https://nc-api-sandbox.zertiban.com

#	Método	Endpoint	Descripción
1	`POST`	`/flow/v1/flows`	Crear flujo
2	`GET`	`/flow/v1/flows`	Listar flujos
3	`GET`	`/flow/v1/flows/{uuid}`	Detalle de flujo
4	`GET`	`/flow/v1/flows/{uuid}/status-histories`	Historial de estados de flujo
5	`GET`	`/flow/v1/flows/statistics`	Estadísticas de flujos
6	`GET`	`/flow/v1/operations`	Listar operaciones
7	`GET`	`/flow/v1/operations/{uuid}`	Detalle de operación
8	`GET`	`/flow/v1/operations/{uuid}/status`	Estado rápido de operación
9	`GET`	`/flow/v1/operations/{uuid}/status-histories`	Historial de estados de operación
10	`GET`	`/flow/v1/operations/statistics`	Estadísticas de operaciones
11	`PUT`	`/flow/v1/operations/{uuid}/cancel`	Cancelar operación
12	`PATCH`	`/flow/v1/operations/{uuid}/expiration`	Ampliar caducidad
13	`GET`	`/flow/v1/operations/{uuid}/payment-documents/{docUuid}/content`	Descargar PDF adjunto
14	`GET`	`/payment/v1/payments/{paymentUuid}`	Detalle del pago PSD2
15	`GET`	`/business-creditor-account/v1/business-creditor-accounts`	Listar cuentas beneficiarias
16	`GET`	`/business-creditor-account/v1/business-creditor-accounts/{uuid}`	Detalle de cuenta beneficiaria
17	`GET`	`/flow-customization/v1/configurations`	Listar configuraciones
18	`GET`	`/flow-customization/v1/configurations/{uuid}`	Detalle de configuración

Errores frecuentes

Código	Causa típica	Solución
`400`	Payload inválido: campo faltante, formato incorrecto, parámetro mal tipado	Revisa la validación en la sección de referencia
`401`	Token expirado o credenciales inválidas	Solicita un nuevo token con Basic Auth
`403`	`x-tenant-id` incorrecto o permisos de credencial insuficientes	Verifica `businessUuid` y los permisos de las credenciales
`404`	UUID de configuración, cuenta, operación, flujo o pago no encontrado	Verifica con los endpoints GET
`409`	Conflicto de estado (cancelar operación finalizada, configuración inactiva)	Consulta el estado actual antes de la acción

Endpoints de negocio ​

Convenciones comunes ​

Flujos ​

1. Crear flujo ​

2. Listar flujos ​

3. Detalle de flujo ​

4. Historial de estados de flujo ​

5. Estadísticas de flujos ​

Operaciones ​

6. Listar operaciones ​

7. Detalle de operación ​

8. Estado rápido de operación ​

9. Historial de estados de operación ​

10. Estadísticas de operaciones ​

11. Cancelar operación ​

12. Ampliar caducidad de operación ​

13. Descargar documento de pago adjunto ​

Pago PSD2 ​

14. Detalle del pago PSD2 ​

Cuentas beneficiarias ​

15. Listar cuentas beneficiarias ​

16. Detalle de cuenta beneficiaria ​

Configuraciones de flujo ​

17. Listar configuraciones ​

18. Detalle de configuración ​

Tabla resumen ​

Errores frecuentes ​

Endpoints de negocio

Convenciones comunes

Flujos

1. Crear flujo

2. Listar flujos

3. Detalle de flujo

4. Historial de estados de flujo

5. Estadísticas de flujos

Operaciones

6. Listar operaciones

7. Detalle de operación

8. Estado rápido de operación

9. Historial de estados de operación

10. Estadísticas de operaciones

11. Cancelar operación

12. Ampliar caducidad de operación

13. Descargar documento de pago adjunto

Pago PSD2

14. Detalle del pago PSD2

Cuentas beneficiarias

15. Listar cuentas beneficiarias

16. Detalle de cuenta beneficiaria

Configuraciones de flujo

17. Listar configuraciones

18. Detalle de configuración

Tabla resumen

Errores frecuentes