Guias Práticos

Fluxo de Criação e Atualização de Filiais

Este fluxo obtém os dados básicos de filiais da base de dados do sistema utilizado pela sua empresa e os mantém atualizados na plataforma da Gupy.

Suggest Edits

Gerando o token

Para utilizar este fluxo, é necessário utilizar o Bearer Token gerado nas configurações avançadas da plataforma. Acesse nossa seção de autenticação para saber como gerar o o token de autenticação.

No momento de gerar o token habilite os seguintes endpoints da V1:

  • Company Branches

Criando as filiais

Acesse o endpoint POST Branches e preencha os parâmetros obrigatórios:

ParâmetroDescrição
codeCódigo atribuído à filial no sistema externo do cliente (deve ser único para cada branch)
nameome da filial (Utilizar o formato: Nome da empresa > Nome da filial)
pathNome da empresa (não são aceitos caracteres especiais, pontos e traços)

Exemplo de requisição

curl --request POST \
     --url https://api.gupy.io/api/v1/branches \
     --header 'accept: application/json' \
     --header 'authorization: Bearer XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
     --header 'content-type: application/json' \
     --data '
{
     "path": [
          "matriz"
     ],
     "code": "1",
     "name": "Matriz",
     "addressCountry": "Brazil",
     "addressCountryShortName": "BR",
     "addressState": "Rio de Janeiro",
     "addressStateShortName": "RJ",
     "addressCity": "Rio de Janeiro",
     "addressStreet": "Rua Visconde de Pirajá",
     "addressNumber": "500",
     "addressZipCode": "20000000"
}
'

Exemplo de resposta

{
  "code": "1",
  "path": [
    "matriz"
  ],
  "name": "Matriz",
  "createdAt": "2023-02-24T20:46:01.929Z",
  "updatedAt": "2023-02-24T20:46:01.929Z",
  "id": 1234,
  "addressNumber": "500",
  "addressStreet": "Rua Visconde de Pirajá",
  "addressCity": "Rio de Janeiro",
  "addressState": "Rio de Janeiro",
  "addressStateShortName": "RJ",
  "addressCountry": "Brazil",
  "addressCountryShortName": "BR",
  "addressZipCode": "20000000",
  "addressLatitude": null,
  "addressLongitude": null
}

Criando sua estrutura organizacional

Caso a sua empresa tenha uma estrutura organizacional com uma matriz, unidades e departamentos é possível criar replicar essa relação através da API, criando associações entre os níveis. A forma de criar essa relação é usando no nome o próximo nível. Veja abaixo um exemplo com 3 níveis.

{
     "path": [
          "Matriz",
     ],
     "code": "1",
     "name": "Matriz"
}

{
     "path": [
          "Matriz",
          "Unidade 1"
     ],
     "code": "1.01",
     "name": "Matriz > Unidade-01"
}

{
     "path": [
          "Matriz",
          "Minas Gerais",
          "Belo Horizonte"
     ],
     "code": "1.01-2",
     "name": "Matriz > Minas Gerais > Belo Horizonte"
}

Atualizando as filiais e Estruturas Organizacionais

🚧

Atenção ao atualizar uma Estrutura Organizacional

  • Caso seja necessário a atualização de algum estrutura, verificar o Path. Ele tem que ser enviado nos casos de criação e/ou atualização;
  • Os paths não podem ser iguais;
  • Importante que todos os níveis tenham código cadastrado, para facilitar na hora da busca por algum nível;
  1. Acesse o endpoint GET Branches
  2. No campo "name" ou "code" filtre pela filial que deseja atualizar
  3. Clique em "Try it!" e salve a branchId
  4. Acesse o endpoint PUT Branches e preencha os parâmetros:
ParâmetroDescrição
codeCódigo atribuído à filial no sistema externo do cliente
nameNome da filial
pathNome da empresa guarda-chuva

Exemplo de requisição

curl --request PUT \
     --url https://api.gupy.io/api/v1/branches/1234 \
     --header 'accept: application/json' \
     --header 'authorization: Bearer XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
     --header 'content-type: application/json' \
     --data '
{
     "path": [
          "matriz"
     ],
     "code": "1",
     "name": "Sede",
     "addressCountry": "Brazil",
     "addressCountryShortName": "BR",
     "addressState": "Rio de Janeiro",
     "addressStateShortName": "RJ",
     "addressCity": "Rio de Janeiro",
     "addressStreet": "Rua Visconde de Pirajá",
     "addressNumber": "500",
     "addressZipCode": "20000000"
}
'

Exemplo de resposta

{
  "code": "1",
  "path": [
    "matriz"
  ],
  "name": "Sede",
  "createdAt": "2023-02-24T20:46:01.929Z",
  "updatedAt": "2023-02-24T20:46:01.929Z",
  "id": 1234,
  "addressNumber": "500",
  "addressStreet": "Rua Visconde de Pirajá",
  "addressCity": "Rio de Janeiro",
  "addressState": "Rio de Janeiro",
  "addressStateShortName": "RJ",
  "addressCountry": "Brazil",
  "addressCountryShortName": "BR",
  "addressZipCode": "20000000",
  "addressLatitude": null,
  "addressLongitude": null
}

Excluindo filiais e Estruturas Organizacionais

📘

Excluindo Estruturas Organizacionais

As E.O só podem ser excluídas quando não tiverem nenhum vínculo com alguma requisição ou usuário. Caso haja a tentativa de exclusão irá gerar um erro. Nossa sugestão para esse caso é criar uma estrutura de inativo e colocar os níveis que precisam ser excluídos nessa nova estrutura para não ficarem no guarda-chuva da E.O ativa

  1. Acesse o endpoint GET Branches
  2. No campo "name" ou "code" filtre pela filial que deseja atualizar
  3. Clique em "Try it!" e salve a branchId
  4. Acesse o endpoint DELETE Branches e preencha a branchId

Exemplo de requisição

curl --request DELETE \
     --url https://api.gupy.io/api/v1/branches/1234 \
     --header 'accept: application/json' \
     --header 'authorization: Bearer XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

Exemplo de resposta

OK

Como ficará essa integração na Gupy? - Filiais

Como ficará essa integração na Gupy? - Estrutura Organizacional

Updated 6 months ago