Ordens de serviço

Cria OS

POST /service-orders

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

A OS nasce em awaiting_invoice. Idempotência comum: a external_reference única já impede OS duplicada.

Parâmetros

Idempotency-Key string · cabeçalho obrigatório

Chave de idempotência gerada por você para a operação (válida por 24 h, por integração). Operação comum: chave "executando" há mais de 60 s é considerada abandonada e o reenvio executa de novo. Mesma chave + mesmo corpo → resposta original com Idempotent-Replayed: true; corpo diferente → 409 IDEMPOTENCY_KEY_CONFLICT. Ausente → 422 IDEMPOTENCY_KEY_MISSING; fora do formato → 422 IDEMPOTENCY_KEY_INVALID.

até 255 caracteres

Corpo da requisição

contact_id integer obrigatório

Contato do tipo cliente, não excluído, da empresa do token. Senão 422 FIELD_INVALID.

external_reference string obrigatório

Referência do pedido no seu sistema — única por empresa (repetir → 409 RESOURCE_ALREADY_EXISTS).

até 120 caracteres

notes string (anulável)

até 2000 caracteres

items array de object obrigatório

1–50 itens

service_id integer obrigatório

Serviço ativo do catálogo da empresa (GET /services). Inexistente, inativo ou de outra empresa → 422 FIELD_INVALID.

description string (anulável)

Padrão: nome do serviço.

até 300 caracteres

quantity number | string obrigatório

Até 3 casas decimais, de 0.001 a 9999999.999.

unit_price number | string obrigatório

Número ou string decimal com até 2 casas, de 0.01 a 99999999.99.

Respostas

201 OS criada.

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

409 external_reference já usada (traz existing_resource_id), limite do plano (traz metric e limit) ou conflito de idempotência. Códigos possíveis: RESOURCE_ALREADY_EXISTS, PLAN_QUOTA_EXCEEDED, 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

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.

422 Dados inválidos, ou Idempotency-Key ausente/inválida. Também: 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' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: pedido-900-os' \
  -d '{"contact_id":4812,"external_reference":"pedido-900","items":[{"service_id":12,"quantity":1,"unit_price":1}]}'

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', [
    'headers' => ['Accept' => 'application/json', 'Authorization' => 'Bearer '.$token, 'Idempotency-Key' => 'pedido-900-os'],
    'json' => [
        'contact_id' => 4812,
        'external_reference' => 'pedido-900',
        'items' => [
            [
                'service_id' => 12,
                'quantity' => 1,
                'unit_price' => 1,
            ],
        ],
    ],
    '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', {
  method: 'POST',
  headers: { 'Accept': 'application/json', Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', 'Idempotency-Key': 'pedido-900-os' },
  body: JSON.stringify({
    "contact_id": 4812,
    "external_reference": "pedido-900",
    "items": [
      {
        "service_id": 12,
        "quantity": 1,
        "unit_price": 1
      }
    ]
  }),
});
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",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}", "Idempotency-Key": "pedido-900-os"},
    json={
        "contact_id": 4812,
        "external_reference": "pedido-900",
        "items": [
            {
                "service_id": 12,
                "quantity": 1,
                "unit_price": 1,
            },
        ],
    },
    timeout=15,
)
data = response.json() if response.status_code != 204 else None

Resposta 201

{
  "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"
  }
}

Erro 422 (exemplo)

{
  "type": "https://cuidaro.com.br/errors/idempotency-key-missing",
  "title": "Idempotency Key Missing",
  "status": 422,
  "detail": "Envie o cabeçalho Idempotency-Key nesta operação.",
  "instance": "/api/v1/service-orders",
  "code": "IDEMPOTENCY_KEY_MISSING"
}