Pessoas
Cadastro de pessoas físicas e jurídicas, com os e-mails e telefones de cada uma. E-mails e telefones são recursos à parte, ligados à pessoa pelo personId.
Pessoas
Recurso do plano: Gestão de Pessoas.
| Método | Rota | O que faz |
|---|---|---|
GET | /external/v1/persons | Lista com paginação |
GET | /external/v1/persons/:id | Busca um registro pelo ID |
POST | /external/v1/persons | Cria um registro |
PUT | /external/v1/persons/:id | Atualiza um registro |
Listar
Aceita page, limit e relations, como descrito em Paginação e filtros.
Exemplo com filtro (o valor de relations vai codificado para URL; aqui ele aparece legível: {"where":{"externalCode":"ERP-000123"}}):
curl -G "https://erp-api.ideros.api.br/external/v1/persons" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN" \
--data-urlencode "page=1" \
--data-urlencode "limit=25" \
--data-urlencode 'relations={"where":{"externalCode":"ERP-000123"}}'
Buscar por ID
curl "https://erp-api.ideros.api.br/external/v1/persons/ID_DO_REGISTRO" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN"
Devolve o registro. Se o ID não existir ou for de outra empresa, a resposta é 200 com corpo {} (objeto vazio).
Criar
Responde 201 com o registro criado.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
country | string | Não | País de origem ou residência da pessoa. Utilizado para validações e formatações específicas por região. |
name | string | Não | Nome completo da pessoa |
socialName | string | Sim | Nome social. Para pessoa física, nome preferido de uso. Para pessoa jurídica, nome comercial/fantasia exibido na interface. |
documentNumber | string | Não | Número de documento da pessoa. Para Brasil, CPF. |
isForeign | boolean | Não | Define se a pessoa é estrangeira. No caso, para BR o documento poderá nessa caso ficar diferente do padrão. |
personType | enum | Sim | Tipo de pessoa cadastrada. Define se é pessoa física (individual) ou pessoa jurídica (empresa). Valores: INDIVIDUAL, COMPANY, INDEFINITE. |
genre | enum | Sim | Sexo da pessoa. Para personType = COMPANY, use INDEFINITE. Valores: MALE, FEMALE, OTHER, INDEFINITE. |
birthDate | string (data ISO 8601) | Não | Data de nascimento da pessoa física ou data de fundação da empresa. |
addressMetadata | object | Não | Endereço: objeto com zipCode, street, streetNumber, complement, neighborhood, city, state, country e ibgeCode (código IBGE do município, resolvido pelo CEP quando falta). |
municipalEnrollment | string | Não | Número de inscrição municipal da pessoa jurídica. |
stateEnrollment | string | Não | Número de inscrição estadual da pessoa jurídica. |
imageUrl | string | Não | URL da foto/logo da pessoa. Foto de perfil. |
externalCode | string | Não | Código externo opcional da pessoa |
tags | string[] | Não | Tags para categorizar e organizar a pessoa. |
metadata | object | Não | Objeto JSON livre. |
classifications | enum[] | Não | Lista de classificações da pessoa. Valores: CUSTOMER, SUPPLIER, EMPLOYEE, CARRIER, CONTRACTOR, COLLABORATOR, CONSULTANT, REPRESENTATIVE, DISTRIBUTOR, RESELLER, PARTNER, AGENT, COMPETITOR, SHAREHOLDER, USER, DEFAULT, BANK. |
supplierTaxRegime | enum | Não | Regime tributário do fornecedor, para o crédito de IBS/CBS nas notas recebidas: NORMAL, SIMPLES_SN (IBS/CBS pelo Simples), SIMPLES_REGULAR (Simples com IBS/CBS pelo regime regular), MEI, NON_TAXPAYER ou UNKNOWN. Informado aqui, vale como escolha manual e não é sobrescrito pelo XML. Valores: NORMAL, SIMPLES_SN, SIMPLES_REGULAR, MEI, NON_TAXPAYER, UNKNOWN. |
governmentEntityType | enum | Não | Tomador público (administração direta, autarquia ou fundação pública): UNION, STATE, DISTRICT ou CITY. Liga o redutor de compra governamental do IBS/CBS (LC 214, art. 472) nas notas emitidas para esta pessoa. Nulo = não é ente público. Sugerido pela natureza jurídica na consulta do CNPJ. Valores: UNION, STATE, DISTRICT, CITY. |
curl -X POST "https://erp-api.ideros.api.br/external/v1/persons" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"personType": "COMPANY",
"name": "Tech Solutions Tecnologia Ltda",
"socialName": "Tech Solutions",
"documentNumber": "12345678000195",
"genre": "INDEFINITE",
"classifications": [
"CUSTOMER"
]
}'
Atualizar
Envie no corpo só os campos que mudam, com os mesmos nomes da tabela de criação. Responde 200 com o registro atualizado. Registro de outra empresa responde 403; registro inexistente, 404.
curl -X PUT "https://erp-api.ideros.api.br/external/v1/persons/ID_DO_REGISTRO" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"tags": [
"vip"
],
"externalCode": "ERP-000123"
}'
O endereço vai em addressMetadata. Ao atualizar, o endereço enviado é mesclado com o que já existe e o código do município é resolvido pelo CEP quando falta.
E-mails da pessoa
Recurso do plano: Gestão de Pessoas.
| Método | Rota | O que faz |
|---|---|---|
GET | /external/v1/person-emails | Lista com paginação |
GET | /external/v1/person-emails/:id | Busca um registro pelo ID |
POST | /external/v1/person-emails | Cria um registro |
PUT | /external/v1/person-emails/:id | Atualiza um registro |
Listar
Aceita page, limit e relations, como descrito em Paginação e filtros.
Exemplo com filtro (o valor de relations vai codificado para URL; aqui ele aparece legível: {"where":{"personId":"ID_DA_PESSOA"}}):
curl -G "https://erp-api.ideros.api.br/external/v1/person-emails" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN" \
--data-urlencode "page=1" \
--data-urlencode "limit=25" \
--data-urlencode 'relations={"where":{"personId":"ID_DA_PESSOA"}}'
Buscar por ID
curl "https://erp-api.ideros.api.br/external/v1/person-emails/ID_DO_REGISTRO" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN"
Devolve o registro. Se o ID não existir ou for de outra empresa, a resposta é 200 com corpo {} (objeto vazio).
Criar
Responde 201 com o registro criado.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
personId | string | Sim | ID de pessoa. |
email | string | Sim | Endereço de e-mail completo. |
contactName | string | Não | Nome de contato ou descrição opcional para este e-mail. |
department | string | Não | Departamento ou setor de contato, caso seja um telefone corporativo. |
isMain | boolean | Sim | Indica se este é o endereço de e-mail principal de contato da pessoa. |
emailActions | enum[] | Não | Lista de ações/tipos de comunicação permitidos para este e-mail. Valores permitidos: 'SEND_INVOICE', 'SEND_BILL', 'SEND_CHARGE', 'SEND_NOTIFICATION', 'STANDARD'. Valores: SEND_INVOICE, SEND_BILL, SEND_CHARGE, SEND_NOTIFICATION, STANDARD. |
curl -X POST "https://erp-api.ideros.api.br/external/v1/person-emails" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"personId": "ID_DA_PESSOA",
"email": "financeiro@techsolutions.com.br",
"isMain": true
}'
Atualizar
Envie no corpo só os campos que mudam, com os mesmos nomes da tabela de criação. Responde 200 com o registro atualizado. Registro de outra empresa responde 403; registro inexistente, 404.
Telefones da pessoa
Recurso do plano: Gestão de Pessoas.
| Método | Rota | O que faz |
|---|---|---|
GET | /external/v1/person-phones | Lista com paginação |
GET | /external/v1/person-phones/:id | Busca um registro pelo ID |
POST | /external/v1/person-phones | Cria um registro |
PUT | /external/v1/person-phones/:id | Atualiza um registro |
Listar
Aceita page, limit e relations, como descrito em Paginação e filtros.
Exemplo com filtro (o valor de relations vai codificado para URL; aqui ele aparece legível: {"where":{"personId":"ID_DA_PESSOA"}}):
curl -G "https://erp-api.ideros.api.br/external/v1/person-phones" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN" \
--data-urlencode "page=1" \
--data-urlencode "limit=25" \
--data-urlencode 'relations={"where":{"personId":"ID_DA_PESSOA"}}'
Buscar por ID
curl "https://erp-api.ideros.api.br/external/v1/person-phones/ID_DO_REGISTRO" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN"
Devolve o registro. Se o ID não existir ou for de outra empresa, a resposta é 200 com corpo {} (objeto vazio).
Criar
Responde 201 com o registro criado.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
personId | string | Sim | ID de pessoa. |
phoneNumber | string | Sim | Número de telefone, sem o código do país. |
countryCode | string | Não | Código internacional do país (DDI), apenas dígitos, sem '+'. Padrão '55' para Brasil. Caso não for informado, será definido com o código do Brasil. |
contactName | string | Não | Nome de contato ou descrição opcional para este telefone. |
department | string | Não | Departamento ou setor de contato, caso seja um telefone corporativo. |
hasSms | boolean | Sim | Indica se este telefone pode receber SMS. |
hasWhatsApp | boolean | Sim | Indica se este telefone possui WhatsApp. |
isMain | boolean | Sim | Indica se este é o telefone principal de contato da pessoa. |
curl -X POST "https://erp-api.ideros.api.br/external/v1/person-phones" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"personId": "ID_DA_PESSOA",
"phoneNumber": "11999998888",
"countryCode": "55",
"hasSms": false,
"hasWhatsApp": true,
"isMain": true
}'
Atualizar
Envie no corpo só os campos que mudam, com os mesmos nomes da tabela de criação. Responde 200 com o registro atualizado. Registro de outra empresa responde 403; registro inexistente, 404.
A nossa equipe ajuda você a configurar e usar esse recurso.