Padrões de Identificação¶

IDs Internos¶

Todos os recursos da API Pontotel possuem um campo id numérico inteiro que serve como identificador único interno.

1
2
3
4

{
  "id": 12345,
  "nome": "João Silva"
}

Chaves de Negócio¶

Além do id interno, cada entidade possui identificadores de negócio:

Formato do CNPJ¶

A API aceita CNPJ com ou sem formatação:

1
2
3
4
5

// Com formatação (recomendado para leitura humana)
{ "cnpj": "12.345.678/0001-99" }

// Sem formatação (aceito)
{ "cnpj": "12345678000199" }

Formato do CPF¶

1
2
3
4
5

// Com formatação
{ "cpf": "123.456.789-00" }

// Sem formatação
{ "cpf": "12345678900" }

Matrícula¶

A matrícula é um identificador alfanumérico livre definido pela empresa:

1
2
3

{ "matricula": "EMP-001" }
{ "matricula": "00123" }
{ "matricula": "FUNC2025001" }

Referência Cruzada (Chave Externa)¶

Ao integrar com outro sistema, use os campos de negócio (cnpj, cpf, matricula) para fazer o vínculo entre os sistemas — não o id interno da Pontotel, que pode variar entre ambientes (sandbox vs. produção).

Padrão Recomendado¶

1
2
3
4
5

# ✅ Busca por chave de negócio (estável entre ambientes)
empregado = api.get("/empregados/", params={"cpf": "12345678900"})

# ❌ Não hardcode IDs internos entre ambientes
empregado = api.get("/empregados/999/")  # ID pode diferir em sandbox

Próximos Passos¶

• Padrões de datas e fusos →
• Paginação e ordenação →