Pular para o conteúdo principal

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étodoRotaO que faz
GET/external/v1/personsLista com paginação
GET/external/v1/persons/:idBusca um registro pelo ID
POST/external/v1/personsCria um registro
PUT/external/v1/persons/:idAtualiza 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.

CampoTipoObrigatórioDescrição
countrystringNãoPaís de origem ou residência da pessoa. Utilizado para validações e formatações específicas por região.
namestringNãoNome completo da pessoa
socialNamestringSimNome social. Para pessoa física, nome preferido de uso. Para pessoa jurídica, nome comercial/fantasia exibido na interface.
documentNumberstringNãoNúmero de documento da pessoa. Para Brasil, CPF.
isForeignbooleanNãoDefine se a pessoa é estrangeira. No caso, para BR o documento poderá nessa caso ficar diferente do padrão.
personTypeenumSimTipo de pessoa cadastrada. Define se é pessoa física (individual) ou pessoa jurídica (empresa). Valores: INDIVIDUAL, COMPANY, INDEFINITE.
genreenumSimSexo da pessoa. Para personType = COMPANY, use INDEFINITE. Valores: MALE, FEMALE, OTHER, INDEFINITE.
birthDatestring (data ISO 8601)NãoData de nascimento da pessoa física ou data de fundação da empresa.
addressMetadataobjectNãoEndereço: objeto com zipCode, street, streetNumber, complement, neighborhood, city, state, country e ibgeCode (código IBGE do município, resolvido pelo CEP quando falta).
municipalEnrollmentstringNãoNúmero de inscrição municipal da pessoa jurídica.
stateEnrollmentstringNãoNúmero de inscrição estadual da pessoa jurídica.
imageUrlstringNãoURL da foto/logo da pessoa. Foto de perfil.
externalCodestringNãoCódigo externo opcional da pessoa
tagsstring[]NãoTags para categorizar e organizar a pessoa.
metadataobjectNãoObjeto JSON livre.
classificationsenum[]NãoLista de classificações da pessoa. Valores: CUSTOMER, SUPPLIER, EMPLOYEE, CARRIER, CONTRACTOR, COLLABORATOR, CONSULTANT, REPRESENTATIVE, DISTRIBUTOR, RESELLER, PARTNER, AGENT, COMPETITOR, SHAREHOLDER, USER, DEFAULT, BANK.
supplierTaxRegimeenumNãoRegime 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.
governmentEntityTypeenumNãoTomador 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"
}'
Endereço

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étodoRotaO que faz
GET/external/v1/person-emailsLista com paginação
GET/external/v1/person-emails/:idBusca um registro pelo ID
POST/external/v1/person-emailsCria um registro
PUT/external/v1/person-emails/:idAtualiza 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.

CampoTipoObrigatórioDescrição
personIdstringSimID de pessoa.
emailstringSimEndereço de e-mail completo.
contactNamestringNãoNome de contato ou descrição opcional para este e-mail.
departmentstringNãoDepartamento ou setor de contato, caso seja um telefone corporativo.
isMainbooleanSimIndica se este é o endereço de e-mail principal de contato da pessoa.
emailActionsenum[]NãoLista 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étodoRotaO que faz
GET/external/v1/person-phonesLista com paginação
GET/external/v1/person-phones/:idBusca um registro pelo ID
POST/external/v1/person-phonesCria um registro
PUT/external/v1/person-phones/:idAtualiza 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.

CampoTipoObrigatórioDescrição
personIdstringSimID de pessoa.
phoneNumberstringSimNúmero de telefone, sem o código do país.
countryCodestringNãoCó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.
contactNamestringNãoNome de contato ou descrição opcional para este telefone.
departmentstringNãoDepartamento ou setor de contato, caso seja um telefone corporativo.
hasSmsbooleanSimIndica se este telefone pode receber SMS.
hasWhatsAppbooleanSimIndica se este telefone possui WhatsApp.
isMainbooleanSimIndica 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.

Ainda com dúvida?

A nossa equipe ajuda você a configurar e usar esse recurso.