Get public list of enabled countries
GET/company/country/
Restituisce una lista paginata di paesi abilitati nel sistema. Questo endpoint fornisce i paesi disponibili per l'uso in moduli, filtri e selezioni geografiche.
Obiettivo
Fornire alle applicazioni frontend e alle integrazioni esterne un elenco aggiornato dei paesi supportati dalla piattaforma per la registrazione delle aziende, la creazione di indirizzi e le operazioni logistiche.
Casi d'uso
- Compilare selettori di paese nei moduli di registrazione
- Mostrare agli utenti le regioni di servizio disponibili
- Filtrare aste o consegne per area geografica
- Convalidare i codici paese forniti dagli utenti
Autenticazione
Questo è un endpoint PUBBLICO. Non richiede autenticazione.
Note importanti
- Restituisce solo paesi con
enabled: true - I paesi con
deleted: trueoenabled: falsesono esclusi - I campi
_id,deleted,enabled,createdAt,updatedAt,__vvengono filtrati dalla risposta - Solo il campo
codeè garantito in tutti i record - I campi opzionali
nameeisopossono essere presenti in alcuni paesi - Paginazione implementata con mongoose-paginate-v2
- La dimensione predefinita della pagina proviene da
process.env.ITEMS_PAGE(normalmente 25)
Esempio di richiesta:
# Ottenere la prima pagina con il limite predefinito (25)
GET /company/country/
# Ottenere la seconda pagina con 10 risultati
GET /company/country/?page=2&limit=10
# Ottenere tutti i paesi disponibili (se sono meno di 50)
GET /company/country/?limit=50
Esempio di risposta:
\{
status: 200,
data: \{
docs: [
\{code: es\},
\{code: pt\},
\{code: fr\},
\{code: de, name: Germania
<Heading
id={"request"}
as={"h2"}
className={"openapi-tabs__heading"}
children={"Request"}
>
</Heading>
<ParamsDetails
parameters={[{"name":"page","in":"query","description":"Numero di pagina da recuperare (indicizzato da 1).\n\n- Valore minimo: 1\n- Predefinito: 1\n- I valori non validi (< 1, NaN) possono essere gestiti da mongoose-paginate","required":false,"schema":{"type":"integer","minimum":1,"default":1,"example":1}},{"name":"limit","in":"query","description":"Numero massimo di risultati per pagina.\n\n- Minimo: 1\n- Predefinito: 25 (da process.env.ITEMS_PAGE)\n- Nota: Attualmente il backend non applica un limite massimo","required":false,"schema":{"type":"integer","minimum":1,"default":25,"example":10}}]}
>
</ParamsDetails>
<RequestSchema
title={"Body"}
body={undefined}
>
</RequestSchema>
<StatusCodes
id={undefined}
label={undefined}
responses={{"200":{"description":"Operazione completata con successo. Restituisce l'elenco paginato dei paesi abilitati.\n\nLa risposta include i metadati completi di impaginazione di mongoose-paginate-v2.","content":{"application/json":{"schema":{"type":"object","required":["status","data"],"properties":{"status":{"type":"integer","description":"Codice di stato HTTP","example":200},"data":{"type":"object","required":["docs","totalDocs","limit","page","totalPages","pagingCounter","hasPrevPage","hasNextPage","prevPage","nextPage"],"description":"Dati di impaginazione generati dal plugin mongoose-paginate-v2.\n\nQuesto oggetto contiene i risultati impaginati e i metadati relativi\nallo stato dell'impaginazione.","properties":{"docs":{"type":"array","description":"Array di documenti paese per la pagina corrente","items":{"type":"object","required":["code"],"properties":{"code":{"type":"string","minLength":2,"maxLength":2,"pattern":"^[a-z]{2}$","description":"Codice paese ISO a 2 lettere (minuscolo).\nQuesto è l'unico campo garantito nelle risposte pubbliche.","example":"es"},"name":{"type":"string","description":"Nome del paese in inglese.\n**OPZIONALE**: Non tutti i paesi hanno questo campo definito.","example":"Spain"},"iso":{"type":"string","minLength":3,"maxLength":3,"pattern":"^[A-Z]{3}$","description":"Codice paese ISO a 3 lettere (ISO 3166-1 alpha-3).\n**OPZIONALE**: Non tutti i paesi hanno questo campo definito.","example":"ESP"}},"description":"Versione pubblica del modello Country restituita da GET /company/country/.\n\nQuesto schema include solo i campi visibili nell'endpoint pubblico.\nI campi interni (`_id`, `deleted`, `enabled`, `createdAt`, `updatedAt`, `__v`)\nvengono filtrati dal controller utilizzando select:\n`-_id -deleted -enabled -createdAt -updatedAt -__v`\n\n**Importante**: Solo `code` è garantito essere presente.\nI campi `name` e `iso` sono opzionali e potrebbero non esistere in tutti i record.","example":{"code":"es","name":"Spain","iso":"ESP"},"title":"CountryPublic"}},"totalDocs":{"type":"integer","description":"Numero totale di documenti corrispondenti al filtro","minimum":0,"example":22},"limit":{"type":"integer","description":"Numero massimo di risultati per pagina","minimum":1,"example":25},"page":{"type":"integer","description":"Numero di pagina corrente (indicizzato a partire da 1)","minimum":1,"example":1},"totalPages":{"type":"integer","description":"Numero totale di pagine disponibili","minimum":1,"example":1},"pagingCounter":{"type":"integer","description":"L'indice iniziale del primo documento nella pagina corrente.\nUtile per visualizzare Mostrando X-Y di Z risultati.","minimum":1,"example":1},"hasPrevPage":{"type":"boolean","description":"Indica se esiste una pagina precedente","example":false},"hasNextPage":{"type":"boolean","description":"Indica se esiste una pagina successiva","example":false},"prevPage":{"type":"integer","nullable":true,"description":"Numero di pagina della pagina precedente.\n`null` se non c'è una pagina precedente.","example":null},"nextPage":{"type":"integer","nullable":true,"description":"Numero di pagina della pagina successiva.\n`null` se non c'è una pagina successiva.","example":null}}}},"description":"Risposta paginata standard per gli endpoint di elenco paesi.\n\nQuesta struttura è utilizzata sia dagli endpoint pubblici che da quelli amministrativi:\n- GET /company/country/ (pubblico, solo abilitati)\n- GET /company/country/all (amministrativo, include i disabilitati)\n\nLa risposta incapsula i dati di impaginazione in una busta API standard:\n`{status: number, data: PaginationObject}`","example":{"status":200,"data":{"docs":[{"code":"es"},{"code":"pt"},{"code":"fr"},{"code":"de","name":"Germany","iso":"DEU"}],"totalDocs":22,"limit":25,"page":1,"totalPages":1,"pagingCounter":1,"hasPrevPage":false,"hasNextPage":false,"prevPage":null,"nextPage":null}},"title":"CountriesResponse"},"example":{"status":200,"data":{"docs":[{"code":"es"},{"code":"pt"},{"code":"fr"},{"code":"de","name":"Germany","iso":"DEU"},{"code":"it","name":"Italy","iso":"ITA"}],"totalDocs":22,"limit":25,"page":1,"totalPages":1,"pagingCounter":1,"hasPrevPage":false,"hasNextPage":false,"prevPage":null,"nextPage":null}}}},"headers":{}},"500":{"description":"Errore interno del server","content":{"application/json":{"schema":{"type":"object","required":["status","message"],"properties":{"status":{"type":"integer","description":"Codice di stato HTTP","minimum":400,"maximum":599,"example":400},"message":{"type":"string","description":"Codice di errore del sistema.\n\nCodici di errore comuni (vedi listado_errores_http.txt per la lista completa):\n- NO_TOKEN (401): Token JWT non fornito\n- TOKEN_NOT_VALID (401): Token JWT non valido o scaduto\n- NO_ADMIN_ROLE (401): L'utente non dispone dei privilegi di amministratore\n- INVALID_PARAMETERS (400): Parametri della richiesta non validi\n- NOT_FOUND (404): Risorsa richiesta non trovata\n- ALREADY_EXIST (401): Risorsa con lo stesso identificatore già esistente\n- UTC_VALIDATION_FAILED (400): Validazione del timestamp UTC fallita\n- INTERNAL_ERROR (500): Si è verificato un errore imprevisto del server\n\nIl messaggio è risolto da `handlerError.getErrorMessage(error)`.","example":"INVALID_PARAMETERS"}},"description":"Formato standard di risposta per errori utilizzato in tutti gli endpoint API.\n\nTutti gli errori seguono lo schema `{status: number, message: string}`.\nIl codice di stato è ripetuto sia nella risposta HTTP che nel corpo.\n\nI messaggi di errore sono costanti definite nel codice e devono essere\ngestiti lato client con messaggi appropriati rivolti all'utente.","example":{"status":400,"message":"INVALID_PARAMETERS"},"title":"ErrorResponse"},"example":{"status":500,"message":"INTERNAL_ERROR"}}}}}}
>
</StatusCodes>