Início rápido

De uma chave de staging a uma chamada funcional em poucos minutos.

Precisa de uma credencial PMS de staging. Se ainda não tiver, peça acesso.

​

1. Defina duas variáveis de ambiente

export TATALLO_BASE_URL="https://staging.api.tatallo.com"
export TATALLO_API_KEY="tat_stg_sk_<credential-id>_<secret>"   # your staging key

Todos os exemplos desta documentação usam estas duas variáveis. Para passar a produção mais tarde, mude TATALLO_BASE_URL para https://api.tatallo.com e use a chave de produção.

​

2. Verifique a sua chave

curl -s "$TATALLO_BASE_URL/v1/me" \
  -H "Authorization: Bearer $TATALLO_API_KEY"

Vê que chave usou, o seu PMS, o ambiente e os âmbitos:

{
  "credential_id": "5d4e040b-61c1-44a4-a4ca-9a751dc05133",
  "pms_name": "Test PMS",
  "environment": "staging",
  "scopes": [
    "properties:read"
  ]
}

credential_id é o ID da sua chave, por isso o seu pode diferir do exemplo. environment deve ser staging e scopes deve incluir properties:read.

​

3. Liste as suas propriedades

curl -s "$TATALLO_BASE_URL/v1/properties" \
  -H "Authorization: Bearer $TATALLO_API_KEY"

Em staging obtém as propriedades fictícias ligadas ao seu PMS, exatamente estas:

{
  "data": [
    {
      "id": "6cfa992d-1805-4de6-892c-23785031aba0",
      "name": "Fixture Loft Kreuzberg",
      "timezone": "Europe/Berlin",
      "status": "active",
      "country": "Germany",
      "city": "Berlin",
      "max_guests": 2,
      "currency": "EUR",
      "updated_at": "2026-10-01T09:00:00.000Z"
    },
    {
      "id": "934f807c-39d6-45de-b107-d5c9e03cb041",
      "name": "Fixture House Alfama",
      "timezone": "Europe/Lisbon",
      "status": "inactive",
      "country": "Portugal",
      "city": "Lisbon",
      "max_guests": 6,
      "currency": "EUR",
      "updated_at": "2026-10-01T09:00:00.000Z"
    },
    {
      "id": "bef2859f-2444-47ec-b5f4-f1e6701f087f",
      "name": "Fixture Apartment Trastevere",
      "timezone": "Europe/Rome",
      "status": "active",
      "country": "Italy",
      "city": "Rome",
      "max_guests": 4,
      "currency": "EUR",
      "updated_at": "2026-10-01T09:00:00.000Z"
    }
  ],
  "page": {
    "next_cursor": null
  }
}

page.next_cursor é null, por isso esta é a lista completa. Com mais propriedades do que cabem numa página, siga o cursor: veja Descoberta de propriedades em staging.

​

4. Leia uma propriedade

curl -s "$TATALLO_BASE_URL/v1/properties/bef2859f-2444-47ec-b5f4-f1e6701f087f" \
  -H "Authorization: Bearer $TATALLO_API_KEY"

{
  "id": "bef2859f-2444-47ec-b5f4-f1e6701f087f",
  "name": "Fixture Apartment Trastevere",
  "timezone": "Europe/Rome",
  "status": "active",
  "country": "Italy",
  "city": "Rome",
  "max_guests": 4,
  "currency": "EUR",
  "updated_at": "2026-10-01T09:00:00.000Z"
}

Guarde o id de cada propriedade na sua tabela de mapeamento: nunca muda. O significado de cada campo: Propriedades.

​

Resolução de problemas

Cada erro tem a mesma forma, { "error": { "code", "message", "request_id" } }. Decida com base em code.

​

401 unauthorized

A chave falta, está mal formada, é do outro ambiente, expirou ou foi revogada. Confirme que TATALLO_API_KEY começa por tat_stg_sk_ quando TATALLO_BASE_URL é staging, que o cabeçalho é exatamente Authorization: Bearer <key> e que nada foi cortado ao copiar. Veja Autenticação.

​

403 insufficient_scope

A chave é válida mas não tem properties:read. GET /v1/me mostra os seus âmbitos. Peça a [e-mail] uma chave com o âmbito necessário.

​

404 property_not_found

A propriedade não está ligada ao seu PMS ou não existe. A Tatallo responde da mesma forma de propósito. Liste primeiro as suas propriedades e use os respetivos id. Veja porque uma propriedade não ligada é um 404.

​

429 rate_limited

Mais de 60 pedidos num minuto com esta chave. Aguarde o número de segundos no cabeçalho Retry-After e tente outra vez.

Quando escrever ao suporte, cite o cabeçalho X-Request-Id da resposta com erro.