Operações disponíveis

A presente seção descreve em detalhe as operações possíveis no Webservice de Ligações Externas para operadores EDI. Em suma, é possível criar uma ligação, consultar o estado de uma ligação, bem como consultar todas as ligações e pedidos de ligação existentes.

Criar pedido de ligação

Para efetuar um pedido de ligação, basta utilizar o método POST /apps/external-connections. Este método permite criar uma ligação entre várias empresas do vosso sistema (entidades externas) e uma empresa do ilink. Os dados a enviar são os seguintes:

Campo	Tipo	Descrição
`externalEntities[0][external_entity_name]`	string	Nome da entidade externa a solicitar ligação
`externalEntities[0][external_entity_nif]`	string	NIF da entidade externa a solicitar ligação, sem prefixo do país
`externalEntities[0][external_entity_country]`	string	País da morada fiscal da entidade externa a solicitar ligação (código ISO 3166 alpha-2)
`entity_nif`	string	NIF da entidade ilink, sem prefixo do país
`entity_country`	string	País da morada fiscal da entidade ilink (código ISO 3166 alpha-2)
`operator_email`	string	Email do operador (para receção de notificações)
`observation`	string	Observação do pedido de ligação externa (opcional)

Exemplo: para o NIF espanhol ESA156565898, os campos de NIF devem ser preenchidos com A156565898 (sem o prefixo do país) e os campos de país com ES.

Nota: A notação de array ([]) indica que é possível enviar várias entidades externas (externalEntities[0], externalEntities[1], etc.), e será criada uma ligação para cada uma delas.

Em caso de sucesso, o método devolve um array com um objeto por cada entidade externa incluída no pedido (externalEntities[]), contendo o id do pedido de ligação criado e o NIF da entidade externa correspondente:

HTTP status: 201 Created

{
  "success": "true",
  "message": {
    "code": "s039",
    "msg": "Ligação externa criada com sucesso."
  },
  "response": [
    {
      "external_entity_nif": "501451676",
      "id": "605369246b3412.42340492"
    },
    {
      "external_entity_nif": "503504564",
      "id": "605369246b3412.42340499"
    }
  ]
}

Note-se que esta ligação ficará também visível no portal de operadores sob o utilizador "Integrador", e serão enviados os e-mails habituais de confirmação e atualização de estados.

Consultar pedido de ligação

Para consultar o estado e os detalhes de um pedido de ligação externa, basta utilizar o método GET /apps/external-connections/{id}, indicando no path o id do pedido de ligação (devolvido no momento da criação do pedido, ver secção anterior).

Em caso de sucesso, o método devolve todos os dados do pedido de ligação, incluindo as entidades envolvidas, o estado atual e, quando aplicável, o motivo de recusa/pendência ou observações da equipa de apoio:

HTTP status: 200 Success

{
  "success": "true",
  "response": {
    "data": {
      "id": "5eb3cfe7a765c2.94780052",
      "person": "João Silva",
      "reference": "LE00001",
      "created_entity_name": "Fornecedor exemplo LDA",
      "state_external_connection": {
        "id": "605369246b3412.42340492",
        "alias": "analyzing",
        "description": "Em análise"
      },
      "type_external_connection": {
        "id": "605369246b3412.42340499",
        "alias": "inbound",
        "description": "Inbound"
      },
      "created_entity": {
        "id": "5c3c5850d4c1d9.94316218",
        "name": "Fornecedor exemplo LDA",
        "nif": "501451676"
      },
      "receiver_entity": {
        "id": "5c5bf2ab882986.42628037",
        "name": "Entidade exemplo LDA",
        "nif": "503504564"
      },
      "observation": "Solicita-se a ligação com o grupo o mais rápido possível.",
      "partner": "EDI A",
      "reason": {
        "reason": "Entidade não reconhecida.",
        "created_at": "2020-06-02 15:51:12"
      },
      "admin_observation": {
        "observation": "Ligação aprovada.",
        "created_at": "2020-06-02 15:51:12"
      },
      "created_at": "2020-05-01 14:07:47",
      "updated_at": "2020-05-01 14:07:47"
    }
  }
}

Campo	Descrição
`reference`	Referência de ligação externa gerada pelo sistema
`created_entity`	Entidade externa que efetuou o pedido de ligação (a mesma indicada em `externalEntities` na criação do pedido)
`receiver_entity`	Entidade ilink para a qual o pedido de ligação foi efetuado
`state_external_connection.alias`	Estado atual do pedido de ligação (ver tabela de estados abaixo)
`type_external_connection.alias`	Tipo de ligação solicitada (sempre Inbound)
`reason`	Motivo de recusa ou pendência do pedido, devolvido apenas quando aplicável
`admin_observation`	Observação registada pela equipa de apoio do ilink relativa ao pedido, devolvida apenas quando aplicável

Os valores possíveis para o campo state_external_connection.alias são os seguintes:

Estado	Descrição
`analyzing`	O pedido de ligação está a ser analisado pela equipa de apoio do ilink
`approved`	O pedido de ligação foi aprovado e a ligação encontra-se ativa
`declined`	O pedido de ligação foi recusado (consulte o campo `reason` para mais detalhes)

Nota: Caso o id indicado não corresponda a nenhum pedido de ligação existente, o método devolve um código de estado HTTP 404 Not Found.

Consultar todas as ligações externas

Este método permite consultar a lista completa de ligações externas efetuadas para o vosso EDI e pode ser consultado em GET /apps/external-connections.

Todos os parâmetros são opcionais e devem ser enviados via query string, permitindo filtrar e paginar os resultados:

Parâmetro	Tipo	Descrição
`reference`	string (query)	Filtrar por referência da ligação externa
`receiver_entity_nif`	string (query)	Filtrar por NIF da entidade recetora
`created_entity_nif`	string (query)	Filtrar por NIF da entidade criadora
`created_at_start`	date (query)	Filtrar por data de criação superior ao valor indicado (e.g 2026-01-01)
`created_at_end`	date (query)	Filtrar por data de criação inferior ao valor indicado (e.g 2026-01-01)
`order`	string (query)	Ordenação dos resultados (`asc` ou `desc`)
`page`	integer (query)	Número da página a obter resultados
`rows`	integer (query)	Número de resultados por página (15 por defeito)

Em caso de sucesso, o método devolve os resultados paginados, com um objeto por cada ligação externa encontrada:

HTTP status: 200 Success

{
  "success": "true",
  "response": {
    "current_page": 1,
    "from": 1,
    "to": 1,
    "total": 1,
    "last_page": 1,
    "per_page": 5,
    "next_page_url": null,
    "prev_page_url": null,
    "data": [
      {
        "id": "5eb3cfe7a765c2.94780052",
        "person": "João Silva",
        "reference": "LE00001",
        "created_entity_name": "Fornecedor exemplo LDA",
        "state_external_connection": {
          "id": "605369246b3412.42340492",
          "alias": "pending",
          "description": "Pendente"
        },
        "type_external_connection": {
          "id": "605369246b3412.42340499",
          "alias": "standard",
          "description": "Padrão"
        },
        "created_entity": {
          "id": "5c3c5850d4c1d9.94316218",
          "name": "Fornecedor exemplo LDA",
          "nif": "501451676"
        },
        "receiver_entity": {
          "id": "5c5bf2ab882986.42628037",
          "name": "Entidade exemplo LDA",
          "nif": "503504564"
        },
        "observation": "Pedido de ligação para faturação eletrónica.",
        "partner": "iGest",
        "reason": {
          "reason": "Entidade não reconhecida.",
          "created_at": "2020-06-02 15:51:12"
        },
        "admin_observation": {
          "observation": "Ligação aprovada.",
          "created_at": "2020-06-02 15:51:12"
        },
        "created_at": "2020-05-01 14:07:47",
        "updated_at": "2020-05-01 14:07:47"
      }
    ]
  }
}

Campo	Descrição
`current_page`	Número da página devolvida
`from` / `to`	Índices do primeiro e último resultado da página atual
`total`	Número total de ligações externas encontradas (todas as páginas)
`last_page`	Número da última página disponível
`per_page`	Número máximo de resultados devolvidos por página
`next_page_url` / `prev_page_url`	URLs para a página seguinte/anterior, ou `null` quando não existem
`data`	Array com as ligações externas encontradas, cada uma seguindo a mesma estrutura descrita na secção Consultar pedido de ligação

Criar pedido de ligação​

Consultar pedido de ligação​

Consultar todas as ligações externas​

Criar pedido de ligação

Consultar pedido de ligação

Consultar todas as ligações externas