Ordens de serviço

Fatura OS com pagamento já recebido fora do Cuidaro (operação estrita)

POST /service-orders/{serviceOrder}/invoice

Escopo services:write
Idempotency-Key obrigatória · estrita
Limite escrita 60/min

Registra o recebível já pago na conta escolhida pela empresa e pede a NFS-e (assíncrona). Se a nota não puder sair, a OS continua faturada e o motivo vem em meta.warnings. Quando a OS emite NFS-e integrada, o endereço completo do cliente e o city_ibge_code coerente com a UF são exigidos antes de faturar (422 com error_codes em contact.address.<campo>). Ordem das conferências: primeiro o estado da OS (já faturada, encerrada ou cancelada → 409 RESOURCE_STATE_CONFLICT, mesmo que a liberação de liquidação externa tenha sido retirada), depois a liberação da integração (422 EXTERNAL_SETTLEMENT_NOT_ALLOWED) e a conta de recebimento (422 EXTERNAL_SETTLEMENT_ACCOUNT_MISSING), depois o valor e o cadastro do cliente.

Parâmetros

Idempotency-Key string · cabeçalho obrigatório

Chave de idempotência — operação estrita (api.idempotent:strict): a chave "executando" nunca é retomada antes de vencer (24 h); todo reenvio com ela recebe 409 IDEMPOTENCY_KEY_IN_PROGRESS. Consulte o recurso pelo GET e, se a operação não aconteceu, reenvie com chave nova. Demais regras iguais às da operação comum.

até 255 caracteres

Corpo da requisição

settlement object obrigatório

type string obrigatório

Só external nesta versão (pagamento já recebido fora do Cuidaro).

Valores: external

paid_at string obrigatório

Y-m-d, não futura.

formato date

method string obrigatório

Valores: pix boleto credit_card debit_card bank_transfer

gateway string obrigatório

até 40 caracteres

gateway_reference string obrigatório

Id do pagamento no gateway. gateway + gateway_reference quitam uma única OS.

até 120 caracteres

amount number | string obrigatório

Igual ao centavo ao total da OS — senão 422 SETTLEMENT_AMOUNT_MISMATCH.

Respostas

200 OS faturada (status: invoiced).

data object obrigatório

id integer obrigatório

number string (anulável) obrigatório

status string obrigatório

Vocabulário público da OS. unknown quando o estado interno não tem correspondência.

Valores: open in_progress awaiting_invoice invoiced closed cancelled unknown

external_reference string (anulável) obrigatório

contact_id integer (anulável) obrigatório

Sem dado pessoal na OS — use GET /contacts/{contact}.

items array de object obrigatório

id integer obrigatório

service_id integer (anulável) obrigatório

description string (anulável) obrigatório

quantity string obrigatório

String decimal com 3 casas.

unit_price string obrigatório

Valor monetário em string decimal com 2 casas.

total string obrigatório

Valor monetário em string decimal com 2 casas.

total string obrigatório

Valor monetário em string decimal com 2 casas.

receivables array de object obrigatório

id integer obrigatório

status string obrigatório

Valores: pending overdue paid cancelled unknown

amount string obrigatório

Valor monetário em string decimal com 2 casas.

amount_paid string obrigatório

Valor monetário em string decimal com 2 casas.

due_date string (anulável) obrigatório

formato date

payment_date string (anulável) obrigatório

formato date

settlement object (anulável) obrigatório

Pagamento externo informado no faturamento pela API, ou null.

type string obrigatório

Valores: external

gateway string obrigatório

gateway_reference string obrigatório

method string obrigatório

paid_at string obrigatório

formato date

amount string obrigatório

Valor monetário em string decimal com 2 casas.

reversed_at string (anulável) obrigatório

formato date-time

fiscal object (anulável) obrigatório

NFS-e mais recente da OS (somente leitura), ou null.

type string obrigatório

Valores: nfse

status string obrigatório

Valores: pending processing issued rejected cancelled cancellation_pending cancellation_error

number string (anulável) obrigatório

null até o provedor informar.

issued_at string (anulável) obrigatório

formato date-time

cancellation_requested_at string (anulável) obrigatório

formato date-time

cancelled_at string (anulável) obrigatório

formato date-time

pdf_url string (anulável) obrigatório

Link assinado do Cuidaro, válido por 24 h; só para nota emitida ou cancelada.

formato uri

xml_url null obrigatório

Ainda não oferecido (sempre null).

created_at string (anulável) obrigatório

formato date-time

billed_at string (anulável) obrigatório

formato date-time

updated_at string (anulável) obrigatório

formato date-time

meta object obrigatório

operation string obrigatório

Valores: invoiced

warnings array de string obrigatório

Avisos em pt-BR (ex.: NFS-e não pôde ser iniciada).

404 Recurso inexistente, excluído ou de outra empresa/integração. Códigos possíveis: RESOURCE_NOT_FOUND.

type string obrigatório

https://cuidaro.com.br/errors/{slug} — ainda não é endereço navegável.

formato uri

title string obrigatório

Título curto e estável por código (inglês).

status integer obrigatório

detail string obrigatório

Texto para pessoas, em pt-BR. Pode mudar; não use para lógica.

instance string obrigatório

Caminho da requisição (ex.: /api/v1/me).

code string obrigatório

Catálogo estável de códigos de erro (App\Enums\ApiErrorCode). Código publicado nunca é renomeado nem removido; códigos novos podem surgir — trate valor desconhecido como erro genérico do status HTTP. O status, o título e o type de cada código estão em x-cuidaro-error-catalog.

Valores: AUTH_CREDENTIALS_INVALID AUTH_TOKEN_EXPIRED AUTH_TOKEN_MISSING AUTH_TOKEN_INVALID AUTH_SCOPE_INSUFFICIENT AUTH_TENANT_SUSPENDED AUTH_TENANT_PLAN_WITHOUT_API ACCESS_DENIED BAD_REQUEST VALIDATION_FAILED FIELD_REQUIRED FIELD_TYPE_INVALID FIELD_MAX_LENGTH FIELD_ENUM_INVALID FIELD_INVALID IDEMPOTENCY_KEY_MISSING IDEMPOTENCY_KEY_INVALID IDEMPOTENCY_KEY_CONFLICT IDEMPOTENCY_KEY_IN_PROGRESS RESOURCE_NOT_FOUND METHOD_NOT_ALLOWED RESOURCE_STATE_CONFLICT PLAN_QUOTA_EXCEEDED PAYLOAD_TOO_LARGE RATE_LIMIT_EXCEEDED HTTP_ERROR INTERNAL_ERROR SERVICE_UNAVAILABLE WEBHOOK_URL_NOT_ALLOWED RESOURCE_ALREADY_EXISTS SETTLEMENT_AMOUNT_MISMATCH EXTERNAL_SETTLEMENT_NOT_ALLOWED EXTERNAL_SETTLEMENT_ACCOUNT_MISSING

metric string

Só em PLAN_QUOTA_EXCEEDED: métrica do plano atingida.

limit integer (anulável)

Só em PLAN_QUOTA_EXCEEDED: limite do plano.

existing_resource_id integer

Só em RESOURCE_ALREADY_EXISTS: id do recurso que já existe.

expected_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: total da OS.

received_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: valor recebido em settlement.amount.

service_order_status string

Só no RESOURCE_STATE_CONFLICT do faturamento: status público atual da OS.

409 OS fora de in_progress/awaiting_invoice ou sem valor (traz service_order_status quando aplicável), pagamento já usado em outra OS (traz existing_resource_id) ou conflito de idempotência. Códigos possíveis: RESOURCE_STATE_CONFLICT, RESOURCE_ALREADY_EXISTS, IDEMPOTENCY_KEY_CONFLICT, IDEMPOTENCY_KEY_IN_PROGRESS.

type string obrigatório

https://cuidaro.com.br/errors/{slug} — ainda não é endereço navegável.

formato uri

title string obrigatório

Título curto e estável por código (inglês).

status integer obrigatório

detail string obrigatório

Texto para pessoas, em pt-BR. Pode mudar; não use para lógica.

instance string obrigatório

Caminho da requisição (ex.: /api/v1/me).

code string obrigatório

metric string

Só em PLAN_QUOTA_EXCEEDED: métrica do plano atingida.

limit integer (anulável)

Só em PLAN_QUOTA_EXCEEDED: limite do plano.

existing_resource_id integer

Só em RESOURCE_ALREADY_EXISTS: id do recurso que já existe.

expected_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: total da OS.

received_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: valor recebido em settlement.amount.

service_order_status string

Só no RESOURCE_STATE_CONFLICT do faturamento: status público atual da OS.

422 Dados inválidos, valor diferente do total (traz expected_amount/received_amount), integração sem permissão ou sem conta de recebimento, cadastro do cliente incompleto para a NFS-e, ou Idempotency-Key ausente/inválida. Também: SETTLEMENT_AMOUNT_MISMATCH, EXTERNAL_SETTLEMENT_NOT_ALLOWED, EXTERNAL_SETTLEMENT_ACCOUNT_MISSING, IDEMPOTENCY_KEY_MISSING, IDEMPOTENCY_KEY_INVALID.

type string obrigatório

https://cuidaro.com.br/errors/{slug} — ainda não é endereço navegável.

formato uri

title string obrigatório

Título curto e estável por código (inglês).

status integer obrigatório

detail string obrigatório

Texto para pessoas, em pt-BR. Pode mudar; não use para lógica.

instance string obrigatório

Caminho da requisição (ex.: /api/v1/me).

code string obrigatório

metric string

Só em PLAN_QUOTA_EXCEEDED: métrica do plano atingida.

limit integer (anulável)

Só em PLAN_QUOTA_EXCEEDED: limite do plano.

existing_resource_id integer

Só em RESOURCE_ALREADY_EXISTS: id do recurso que já existe.

expected_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: total da OS.

received_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: valor recebido em settlement.amount.

service_order_status string

Só no RESOURCE_STATE_CONFLICT do faturamento: status público atual da OS.

errors object

Mensagens por campo (pt-BR).

error_codes object

Códigos estáveis por campo: FIELD_REQUIRED, FIELD_TYPE_INVALID, FIELD_MAX_LENGTH, FIELD_ENUM_INVALID, FIELD_INVALID, WEBHOOK_URL_NOT_ALLOWED.

401 Token ausente, inválido, revogado ou expirado. Códigos: AUTH_TOKEN_MISSING, AUTH_TOKEN_INVALID, AUTH_TOKEN_EXPIRED.

type string obrigatório

https://cuidaro.com.br/errors/{slug} — ainda não é endereço navegável.

formato uri

title string obrigatório

Título curto e estável por código (inglês).

status integer obrigatório

detail string obrigatório

Texto para pessoas, em pt-BR. Pode mudar; não use para lógica.

instance string obrigatório

Caminho da requisição (ex.: /api/v1/me).

code string obrigatório

metric string

Só em PLAN_QUOTA_EXCEEDED: métrica do plano atingida.

limit integer (anulável)

Só em PLAN_QUOTA_EXCEEDED: limite do plano.

existing_resource_id integer

Só em RESOURCE_ALREADY_EXISTS: id do recurso que já existe.

expected_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: total da OS.

received_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: valor recebido em settlement.amount.

service_order_status string

Só no RESOURCE_STATE_CONFLICT do faturamento: status público atual da OS.

403 Escopo insuficiente ou empresa sem acesso à API. Códigos possíveis: AUTH_SCOPE_INSUFFICIENT, AUTH_TENANT_SUSPENDED, AUTH_TENANT_PLAN_WITHOUT_API, ACCESS_DENIED.

type string obrigatório

https://cuidaro.com.br/errors/{slug} — ainda não é endereço navegável.

formato uri

title string obrigatório

Título curto e estável por código (inglês).

status integer obrigatório

detail string obrigatório

Texto para pessoas, em pt-BR. Pode mudar; não use para lógica.

instance string obrigatório

Caminho da requisição (ex.: /api/v1/me).

code string obrigatório

metric string

Só em PLAN_QUOTA_EXCEEDED: métrica do plano atingida.

limit integer (anulável)

Só em PLAN_QUOTA_EXCEEDED: limite do plano.

existing_resource_id integer

Só em RESOURCE_ALREADY_EXISTS: id do recurso que já existe.

expected_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: total da OS.

received_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: valor recebido em settlement.amount.

service_order_status string

Só no RESOURCE_STATE_CONFLICT do faturamento: status público atual da OS.

413 Corpo acima de 512 KB. Códigos possíveis: PAYLOAD_TOO_LARGE.

type string obrigatório

https://cuidaro.com.br/errors/{slug} — ainda não é endereço navegável.

formato uri

title string obrigatório

Título curto e estável por código (inglês).

status integer obrigatório

detail string obrigatório

Texto para pessoas, em pt-BR. Pode mudar; não use para lógica.

instance string obrigatório

Caminho da requisição (ex.: /api/v1/me).

code string obrigatório

metric string

Só em PLAN_QUOTA_EXCEEDED: métrica do plano atingida.

limit integer (anulável)

Só em PLAN_QUOTA_EXCEEDED: limite do plano.

existing_resource_id integer

Só em RESOURCE_ALREADY_EXISTS: id do recurso que já existe.

expected_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: total da OS.

received_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: valor recebido em settlement.amount.

service_order_status string

Só no RESOURCE_STATE_CONFLICT do faturamento: status público atual da OS.

429 Limite de requisições excedido. Código: RATE_LIMIT_EXCEEDED.

type string obrigatório

https://cuidaro.com.br/errors/{slug} — ainda não é endereço navegável.

formato uri

title string obrigatório

Título curto e estável por código (inglês).

status integer obrigatório

detail string obrigatório

Texto para pessoas, em pt-BR. Pode mudar; não use para lógica.

instance string obrigatório

Caminho da requisição (ex.: /api/v1/me).

code string obrigatório

metric string

Só em PLAN_QUOTA_EXCEEDED: métrica do plano atingida.

limit integer (anulável)

Só em PLAN_QUOTA_EXCEEDED: limite do plano.

existing_resource_id integer

Só em RESOURCE_ALREADY_EXISTS: id do recurso que já existe.

expected_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: total da OS.

received_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: valor recebido em settlement.amount.

service_order_status string

Só no RESOURCE_STATE_CONFLICT do faturamento: status público atual da OS.

500 Erro interno, sem mensagem interna nem stack trace. Códigos possíveis: INTERNAL_ERROR.

type string obrigatório

https://cuidaro.com.br/errors/{slug} — ainda não é endereço navegável.

formato uri

title string obrigatório

Título curto e estável por código (inglês).

status integer obrigatório

detail string obrigatório

Texto para pessoas, em pt-BR. Pode mudar; não use para lógica.

instance string obrigatório

Caminho da requisição (ex.: /api/v1/me).

code string obrigatório

metric string

Só em PLAN_QUOTA_EXCEEDED: métrica do plano atingida.

limit integer (anulável)

Só em PLAN_QUOTA_EXCEEDED: limite do plano.

existing_resource_id integer

Só em RESOURCE_ALREADY_EXISTS: id do recurso que já existe.

expected_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: total da OS.

received_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: valor recebido em settlement.amount.

service_order_status string

Só no RESOURCE_STATE_CONFLICT do faturamento: status público atual da OS.

Requisição

cURL

curl -X POST 'https://cuidaro.com.br/api/v1/service-orders/731/invoice' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: pedido-900-pago' \
  -d '{"settlement":{"type":"external","paid_at":"2026-10-27","method":"pix","gateway":"asaas","gateway_reference":"pay_exemplo900","amount":"149.90"}}'

PHP

// composer require guzzlehttp/guzzle
$client = new \GuzzleHttp\Client(['base_uri' => 'https://cuidaro.com.br/api/v1/']);
$token = getenv('CUIDARO_TOKEN');

$response = $client->request('POST', 'service-orders/731/invoice', [
    'headers' => ['Accept' => 'application/json', 'Authorization' => 'Bearer '.$token, 'Idempotency-Key' => 'pedido-900-pago'],
    'json' => [
        'settlement' => [
            'type' => 'external',
            'paid_at' => '2026-10-27',
            'method' => 'pix',
            'gateway' => 'asaas',
            'gateway_reference' => 'pay_exemplo900',
            'amount' => '149.90',
        ],
    ],
    'http_errors' => false,
]);

$data = json_decode((string) $response->getBody(), true);

Node.js

const token = process.env.CUIDARO_TOKEN;

const response = await fetch('https://cuidaro.com.br/api/v1/service-orders/731/invoice', {
  method: 'POST',
  headers: { 'Accept': 'application/json', Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', 'Idempotency-Key': 'pedido-900-pago' },
  body: JSON.stringify({
    "settlement": {
      "type": "external",
      "paid_at": "2026-10-27",
      "method": "pix",
      "gateway": "asaas",
      "gateway_reference": "pay_exemplo900",
      "amount": "149.90"
    }
  }),
});
const data = response.status === 204 ? null : await response.json();

Python

import os

import requests

token = os.environ["CUIDARO_TOKEN"]

response = requests.request(
    "POST",
    "https://cuidaro.com.br/api/v1/service-orders/731/invoice",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}", "Idempotency-Key": "pedido-900-pago"},
    json={
        "settlement": {
            "type": "external",
            "paid_at": "2026-10-27",
            "method": "pix",
            "gateway": "asaas",
            "gateway_reference": "pay_exemplo900",
            "amount": "149.90",
        },
    },
    timeout=15,
)
data = response.json() if response.status_code != 204 else None

Resposta 200

{
  "data": {
    "id": 731,
    "number": "1000",
    "status": "open",
    "external_reference": "pedido-900",
    "contact_id": 4812,
    "items": [
      {
        "id": 731,
        "service_id": 12,
        "description": "texto",
        "quantity": "1.000",
        "unit_price": "149.90",
        "total": "149.90"
      }
    ],
    "total": "149.90",
    "receivables": [
      {
        "id": 731,
        "status": "pending",
        "amount": "149.90",
        "amount_paid": "149.90",
        "due_date": "2026-10-27",
        "payment_date": "2026-10-27"
      }
    ],
    "settlement": {
      "type": "external",
      "gateway": "asaas",
      "gateway_reference": "pay_exemplo900",
      "method": "pix",
      "paid_at": "2026-10-27",
      "amount": "149.90",
      "reversed_at": "2026-10-27T11:00:00-03:00"
    },
    "fiscal": {
      "type": "nfse",
      "status": "pending",
      "number": "1000",
      "issued_at": "2026-10-27T11:00:00-03:00",
      "cancellation_requested_at": "2026-10-27T11:00:00-03:00",
      "cancelled_at": "2026-10-27T11:00:00-03:00",
      "pdf_url": "https://cuidaro.com.br/…",
      "xml_url": null
    },
    "created_at": "2026-10-27T11:00:00-03:00",
    "billed_at": "2026-10-27T11:00:00-03:00",
    "updated_at": "2026-10-27T11:00:00-03:00"
  },
  "meta": {
    "operation": "invoiced",
    "warnings": [
      "texto"
    ]
  }
}

Erro 422 (exemplo)

{
  "type": "https://cuidaro.com.br/errors/settlement-amount-mismatch",
  "title": "Settlement Amount Mismatch",
  "status": 422,
  "detail": "O valor da liquidação é diferente do total da OS.",
  "instance": "/api/v1/service-orders/731/invoice",
  "code": "SETTLEMENT_AMOUNT_MISMATCH"
}