Clientes

Cadastra ou reaproveita cliente pelo CPF/CNPJ

POST /contacts

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

Documento novo → cria (201). Documento já cadastrado → 200 matched, preenchendo só campos vazios no Cuidaro. Cadastro excluído com o documento → reativado, 200 restored.

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

document string obrigatório

CPF ou CNPJ válido, com ou sem pontuação. Chave do upsert.

até 20 caracteres

name string obrigatório

até 255 caracteres

trading_name string (anulável)

até 255 caracteres

email string (anulável)

até 255 caracteres · formato email

nfe_email string (anulável)

até 255 caracteres · formato email

phone string (anulável)

até 20 caracteres

mobile string (anulável)

até 20 caracteres

state_registration string (anulável)

até 50 caracteres

address object (anulável)

zip_code string (anulável)

até 10 caracteres

street string (anulável)

até 255 caracteres

number string (anulável)

até 20 caracteres

complement string (anulável)

até 100 caracteres

neighborhood string (anulável)

até 100 caracteres

city string (anulável)

até 100 caracteres

state string (anulável)

UF com 2 letras (normalizada para maiúsculas). Obrigatória quando vier city_ibge_code.

city_ibge_code string | integer | null

Código IBGE do município (7 dígitos; número também é aceito). Precisa pertencer à UF informada — senão 422.

Respostas

200 Cliente existente reaproveitado (matched) ou reativado (restored).

data object obrigatório

id integer obrigatório

types array de string obrigatório

Valores conhecidos: customer, supplier, employee.

status string (anulável) obrigatório

Valores conhecidos: active, inactive, blocked.

person_type string (anulável) obrigatório

individual (CPF) ou company (CNPJ).

name string obrigatório

trading_name string (anulável) obrigatório

document string (anulável) obrigatório

Só dígitos (e letras, no CNPJ alfanumérico).

email string (anulável) obrigatório

nfe_email string (anulável) obrigatório

phone string (anulável) obrigatório

mobile string (anulável) obrigatório

state_registration string (anulável) obrigatório

address object obrigatório

zip_code string (anulável) obrigatório

street string (anulável) obrigatório

number string (anulável) obrigatório

complement string (anulável) obrigatório

neighborhood string (anulável) obrigatório

city string (anulável) obrigatório

state string (anulável) obrigatório

city_ibge_code string (anulável) obrigatório

created_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: created matched restored

201 Cliente criado (created).

data object obrigatório

id integer obrigatório

types array de string obrigatório

Valores conhecidos: customer, supplier, employee.

status string (anulável) obrigatório

Valores conhecidos: active, inactive, blocked.

person_type string (anulável) obrigatório

individual (CPF) ou company (CNPJ).

name string obrigatório

trading_name string (anulável) obrigatório

document string (anulável) obrigatório

Só dígitos (e letras, no CNPJ alfanumérico).

email string (anulável) obrigatório

nfe_email string (anulável) obrigatório

phone string (anulável) obrigatório

mobile string (anulável) obrigatório

state_registration string (anulável) obrigatório

address object obrigatório

zip_code string (anulável) obrigatório

street string (anulável) obrigatório

number string (anulável) obrigatório

complement string (anulável) obrigatório

neighborhood string (anulável) obrigatório

city string (anulável) obrigatório

state string (anulável) obrigatório

city_ibge_code string (anulável) obrigatório

created_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: created matched restored

409 Limite do plano (traz metric e limit), mais de um cadastro excluído com o documento, ou conflito de idempotência. Códigos possíveis: PLAN_QUOTA_EXCEEDED, RESOURCE_STATE_CONFLICT, 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 Documento ausente/inválido, IBGE inválido ou de outra UF, 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/contacts' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: pedido-900-contato' \
  -d '{"document":"52998224725","name":"Maria da Silva","email":"maria@example.com","phone":"1633334444","mobile":"16999990000"}'

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', 'contacts', [
    'headers' => ['Accept' => 'application/json', 'Authorization' => 'Bearer '.$token, 'Idempotency-Key' => 'pedido-900-contato'],
    'json' => [
        'document' => '52998224725',
        'name' => 'Maria da Silva',
        'email' => 'maria@example.com',
        'phone' => '1633334444',
        'mobile' => '16999990000',
    ],
    '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/contacts', {
  method: 'POST',
  headers: { 'Accept': 'application/json', Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', 'Idempotency-Key': 'pedido-900-contato' },
  body: JSON.stringify({
    "document": "52998224725",
    "name": "Maria da Silva",
    "email": "maria@example.com",
    "phone": "1633334444",
    "mobile": "16999990000"
  }),
});
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/contacts",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}", "Idempotency-Key": "pedido-900-contato"},
    json={
        "document": "52998224725",
        "name": "Maria da Silva",
        "email": "maria@example.com",
        "phone": "1633334444",
        "mobile": "16999990000",
    },
    timeout=15,
)
data = response.json() if response.status_code != 204 else None

Resposta 200

{
  "data": {
    "id": 731,
    "types": [
      "texto"
    ],
    "status": "texto",
    "person_type": "texto",
    "name": "Maria da Silva",
    "trading_name": "texto",
    "document": "52998224725",
    "email": "maria@example.com",
    "nfe_email": "texto",
    "phone": "1633334444",
    "mobile": "16999990000",
    "state_registration": "texto",
    "address": {
      "zip_code": "01310-100",
      "street": "Av. Paulista",
      "number": "1000",
      "complement": "texto",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "city_ibge_code": "3550308"
    },
    "created_at": "2026-10-27T11:00:00-03:00",
    "updated_at": "2026-10-27T11:00:00-03:00"
  },
  "meta": {
    "operation": "created"
  }
}

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/contacts",
  "code": "IDEMPOTENCY_KEY_MISSING"
}